Skip to content

osrlib.core.monsters

Monster templates, the creatures spawned from them, and the ids they are given.

A monster has two models. A MonsterTemplate is a stat block: the shared description of one kind of creature, so one troll template describes every troll. A MonsterInstance is one creature in play, with separate hit points, wounds, and conditions. You spawn an instance from a template, and a change to the instance doesn't change the template or the other instances spawned from it.

The members, in the order you use them:

Every model here except MonsterInstance and IdAllocator is frozen: assigning to one of its fields raises pydantic.ValidationError. Their mapping fields, like an ability's params, are read-only FrozenMaps, so a template can't be changed at any depth.

A monster instance is a combatant. Pass it to the functions in osrlib.core.combat, which take a Character or a monster instance as attacker or target, and to osrlib.core.effects for conditions and timed modifiers. For its treasure, pass the template's TreasureRef to plan_treasure_ref. The experience it's worth is the template's xp.

What a monster can do beyond its attacks is on the template as MonsterAbility records. Each record has a tag, the OSE SRD's text, and the numbers the OSE SRD gives, in params. The combat functions read four tags: regeneration in deal_damage, energy_drain in resolve_energy_drain, breath_weapon in resolve_breath, and uses_fire in check_immunity. A battle in a GameSession also reads paralysis, poison, disease, petrification, and blindness when a monster's attack hits. An ability whose manual is True is text for a referee to read, and osrlib doesn't act on it. What a monster resists is in Defenses, which the combat functions check every time an attack hits.

The catalog has a separate template for each creature the OSE SRD describes. Where one monster entry covers several sizes, like the hydras, each size has its own template. The templates of one creature share a family_id, and MonsterCatalog.family returns them.

spawn_monster rolls hit points from the stream named by MONSTER_SPAWN_STREAM, not the combat stream. So in a game with a fixed seed, combat rolls never change the hit points of monsters that spawn later.

Typical usage:

from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters

allocator = IdAllocator()
stream = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
template = load_monsters().get("troll")
troll = spawn_monster(template, id=allocator.allocate("monster"), stream=stream)
print(troll.id, troll.name, troll.max_hp, troll.armour_class, troll.thac0)
# monster-0001 Troll 42 4 13
print(template.xp, template.ability("regeneration").params["per_round"])
# 650 3

MONSTER_SPAWN_STREAM module-attribute

MONSTER_SPAWN_STREAM = StreamName.MONSTER_SPAWN

The stream key every session uses for rolling a spawned monster's hit points.

A stream key identifies one independent random-number sequence inside an RngStreams set. Pass streams.get(MONSTER_SPAWN_STREAM) as the stream argument of spawn_monster.

It is separate from the combat stream so that a change to how a fight resolves never changes the creatures that spawn in a seeded scenario.

AcAlternate

Bases: BaseModel

An armour class a monster has only in particular circumstances.

Read them from MonsterTemplate.ac_alternates. The SRD prints more than one armour class for a creature that changes shape, or for a band whose members wear different armour. The template's ac is the usual value, and these are the others. Deciding when one applies is the referee's call, and osrlib never switches to one. Frozen.

ac instance-attribute

ac: int

The armour class in the descending presentation, where lower is better.

ac_ascending instance-attribute

ac_ascending: int

The same armour class in the ascending presentation, where higher is better.

condition class-attribute instance-attribute

condition: str = ''

When this value applies, in the SRD's words, like "in human form".

Empty when the SRD prints the alternative without a condition, as it does for a band whose members wear different armour.

AlignmentSpec

Bases: BaseModel

Which alignments a monster may have, and which it usually has.

Read it as MonsterTemplate.alignment. spawn_monster gives each creature it spawns one alignment, because the wards that depend on alignment, like protection from evil, need one alignment to test against. Frozen.

options class-attribute instance-attribute

options: tuple[Alignment, ...] = Field(min_length=1)

The alignments this creature may have, at least one. A troll is always chaotic. A creature the SRD prints as any alignment has all three here.

usual class-attribute instance-attribute

usual: Alignment | None = None

Which of the options the creature usually has, when the SRD gives one. None when it doesn't.

A creature with several options and no usual one spawns with no alignment unless you pass one to spawn_monster.

AttackRoutine

Bases: BaseModel

One set of attacks a monster can make in a round, chosen as a whole.

Read them from MonsterTemplate.attacks. Most creatures have one. A creature with more than one uses one of them in a round, not all of them: a dragon either claws and bites or breathes. Each attack in the routine is a MonsterAttack. The routine's use says when the OSE SRD lets the monster use it. In battle, an ActionPolicy picks one each round. The model is frozen (immutable).

attacks class-attribute instance-attribute

attacks: tuple[MonsterAttack, ...] = Field(min_length=1)

The attacks the routine makes, at least one. See MonsterAttack.

use class-attribute instance-attribute

When the monster uses this routine. See RoutineUse.

The first routine of a template is PRIMARY. In the built-in catalog, every later routine has one of the other values, taken from the OSE SRD's text for that monster. In a template of your own, set use on each later routine. A routine you leave unset is PRIMARY too, so the default policy picks it as often as the first.

DamageKey

Bases: StrEnum

A kind of damage source that a monster's defenses can list.

For a monster that only certain kinds of attack can hurt, Defenses.harmed_only_by lists them. For a monster that takes reduced damage from a kind, DamageReduction.keys lists it. The damage rules compare these with the keys and the element of the attack's DamageSource.

holy works differently from the others. Holy water presents it, and against an undead target it gets past any harmed_only_by list, because in the SRD holy water harms undead. Without that exception, the wight's silver-or-magic list would stop holy water. Against a target that isn't undead, a holy source does no damage.

SILVER class-attribute instance-attribute

SILVER = 'silver'

A silver weapon, which harms a wight, a wraith, or a werewolf that steel can't.

MAGIC class-attribute instance-attribute

MAGIC = 'magic'

An enchanted weapon or a spell.

FIRE class-attribute instance-attribute

FIRE = 'fire'

Fire, whether from a torch, a flask of oil, or a spell.

COLD class-attribute instance-attribute

COLD = 'cold'

Cold, from a creature's attack or a spell.

HOLY class-attribute instance-attribute

HOLY = 'holy'

Holy water, which harms undead whatever else they resist.

DamageReduction

Bases: BaseModel

A reduction of the damage a monster takes, applied after the dice are rolled.

Read them from Defenses.reductions. deal_damage divides the damage by divisor and rounds down, and a hit that gets through always does at least 1 point. Frozen.

keys class-attribute instance-attribute

keys: tuple[DamageKey, ...] = ()

Which sources of damage are reduced.

Empty means every source that gets past harmed_only_by, as with the mummy, which takes half damage from everything. A list of keys limits the reduction to sources that present one of them, as with the wraith, which takes half damage from silver weapons only.

divisor class-attribute instance-attribute

divisor: int = Field(default=2, ge=2)

What the damage is divided by, 2 or more. The SRD prints only halving, which is 2.

Defenses

Bases: BaseModel

What a monster resists, in the form the damage rules check.

Read it as MonsterTemplate.defenses. Every time an attack hits, check_immunity reads it before any damage is rolled, and deal_damage applies the reductions. The SRD's wording for the same defenses is in the template's abilities, for you to show. Frozen.

harmed_only_by class-attribute instance-attribute

harmed_only_by: tuple[DamageKey, ...] = ()

The kinds of damage that can hurt this creature at all.

An attack that presents none of them is absorbed, and no damage is rolled. That is how a wight ignores an ordinary sword. Empty means anything hurts it.

reductions class-attribute instance-attribute

reductions: tuple[DamageReduction, ...] = ()

Reductions of the damage that does get through. See DamageReduction.

energy class-attribute instance-attribute

How the creature resists each kind of energy, keyed by element. See EnergyDefense. An element with no entry hurts it as usual.

condition_immunities class-attribute instance-attribute

condition_immunities: tuple[Condition, ...] = ()

Conditions the creature can never be put into, like the undead's immunity to being poisoned, charmed, or put to sleep. grant_condition grants nothing when you try.

Element

Bases: StrEnum

A kind of energy that a breath weapon, an attack, or a spell can deal, and a monster can resist.

A dragon's breath has one of these elements, and so does each entry in Defenses.energy. Before any damage is rolled, the combat functions look up the attack's element there to decide whether the attack hurts the monster at all.

FIRE class-attribute instance-attribute

FIRE = 'fire'

Fire, as a red dragon breathes and a fire giant ignores.

COLD class-attribute instance-attribute

COLD = 'cold'

Cold, as a white dragon breathes.

LIGHTNING class-attribute instance-attribute

LIGHTNING = 'lightning'

Lightning, as a blue dragon breathes.

ACID class-attribute instance-attribute

ACID = 'acid'

Acid, as a black dragon breathes.

GAS class-attribute instance-attribute

GAS = 'gas'

Poisonous gas, as a green dragon breathes.

POISON class-attribute instance-attribute

POISON = 'poison'

Poison that isn't a gas, as a sea dragon spits.

STEAM class-attribute instance-attribute

STEAM = 'steam'

Scalding steam, as a dragon turtle breathes.

EnergyDefense

Bases: BaseModel

How a monster resists one kind of energy.

Read them from Defenses.energy, keyed by Element. Before rolling damage, check_immunity looks up the element of the incoming attack, and saving_throw reads auto_save_magical. Frozen.

immunity instance-attribute

immunity: Literal['all', 'nonmagical']

How much of this element the creature ignores.

"all" means no damage of this element hurts the creature, magical or not, as with a fire giant and fire. "nonmagical" means only magical damage of this element hurts it. A red dragon takes no damage from a dragon's fire breath or a flask of burning oil, and still takes damage from a fire ball.

auto_save_magical class-attribute instance-attribute

auto_save_magical: bool = False

True when the creature passes every saving throw against a magical form of this element without rolling.

This is a dragon's automatic save against a spell of the element it resists, like a red dragon's save against fire ball, so it takes half damage.

IdAllocator

Bases: BaseModel

Hands out entity ids, each one unique within a game.

Every creature, effect, and valuable in a game needs an id, and an allocator gives it one. A GameSession has one allocator and uses it everywhere it needs an id, so inside a session, pass the session's allocator rather than a new one. Outside a session, construct one and pass the same one to every call that takes an allocator.

Ids count up per prefix and never repeat, so a save and its replay refer to the same creature by the same id. The counters are a plain field, so you can save and load an allocator with model_dump and model_validate, and it continues the count.

Examples:

from osrlib.core.monsters import IdAllocator

allocator = IdAllocator()
print(allocator.allocate("monster"), allocator.allocate("monster"))
# monster-0001 monster-0002
print(allocator.allocate("effect"))
# effect-0001

counters class-attribute instance-attribute

counters: dict[str, int] = {}

How many ids have been handed out under each prefix, keyed by prefix.

allocate updates it. Don't set it yourself, or the allocator can hand out an id it has already given.

allocate

allocate(prefix: str) -> str

Return the next unused id under prefix.

Each prefix counts independently and never repeats, so calling it twice with the same prefix gives two different ids. It mutates the allocator, so an id is spent once it is returned.

Parameters:

Name Type Description Default
prefix str

What kind of thing the id is for, like "monster", "effect", "npc", or "valuable".

required

Returns:

Type Description
str

The id, which is the prefix, a hyphen, and a number padded to at least four digits, counting from 0001.

Examples:

from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters

allocator = IdAllocator()
stream = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
goblin = load_monsters().get("goblin")
goblins = [spawn_monster(goblin, id=allocator.allocate("monster"), stream=stream) for _ in range(3)]
print([goblin.id for goblin in goblins])
# ['monster-0001', 'monster-0002', 'monster-0003']

# The counters are plain data, so a saved allocator resumes the count.
restored = IdAllocator.model_validate(allocator.model_dump())
print(restored.allocate("monster"))
# monster-0004

MonsterAbility

Bases: BaseModel

One thing a monster can do, as a tag plus the SRD text it came from.

Read them from MonsterTemplate.abilities, or look one up by tag with MonsterTemplate.ability. The combat functions find an ability by its tag and read the numbers in params, so a monster's special powers are data rather than code. Frozen.

An ability marked manual is text for a referee to read and act on, and osrlib doesn't use it.

tag class-attribute instance-attribute

tag: str = Field(min_length=1)

The ability's identifier, a lowercase name like "regeneration".

The combat functions read four tags: "regeneration", "energy_drain", "breath_weapon", and "uses_fire". A battle in a GameSession also reads these:

  • "paralysis", "poison", "disease", "petrification", and "blindness", when a monster's attack hits.
  • "averting_eyes", for the bonus a gazer gets against a creature that averts its eyes.
  • "surprise", when its params have meets_gaze. Every character the monster surprises is then affected by its gaze, as with a basilisk.
  • attacks_others in the params of a "paralysis" ability, as the ghoul's and the thoul's have. The default action policy then has the monster pass over every paralysed member, whoever paralysed them, while a target that's neither paralysed nor turned to stone is in reach.

name class-attribute instance-attribute

name: str = Field(min_length=1)

The ability's name as the SRD prints it, for display.

prose instance-attribute

prose: str

The SRD's description, to show a player or referee.

manual class-attribute instance-attribute

manual: bool = False

True when osrlib doesn't act on this ability, so the referee applies it from the description.

params class-attribute instance-attribute

params: Annotated[Mapping[str, int | str | bool | tuple[int | str, ...]], FrozenMap] = FrozenMap()

The numbers and options the SRD gives for the ability, keyed by name.

A troll's regeneration has delay_rounds 3 and per_round 3, and a wight's energy drain has levels 1. The keys differ by tag. Empty when the SRD gives no numbers.

MonsterAttack

Bases: BaseModel

One attack a monster makes: its name, how often it's made, how much it hurts, and what else it does.

Read them from AttackRoutine.attacks, and pass one to resolve_attack as the attack. A troll's routine is two talon attacks and a bite, so it has two of these, and the talon's count is 2.

Constructing one raises pydantic.ValidationError when damage is not a valid dice expression. Frozen.

count class-attribute instance-attribute

count: int = Field(default=1, ge=1)

How many of this attack the monster makes in a round.

name class-attribute instance-attribute

name: str = Field(min_length=1)

The attack's name as the SRD prints it, like "talon", "bite", or "weapon".

damage class-attribute instance-attribute

damage: str | None = None

The damage as a dice expression, like "1d6", which roll evaluates.

None when the damage is fixed, and when the attack has no damage dice, like a dragon's breath, whose damage comes from its breath_weapon ability.

fixed_damage class-attribute instance-attribute

fixed_damage: int | None = None

Damage that is a flat number rather than a roll. None when damage is set.

fixed_damage_options class-attribute instance-attribute

fixed_damage_options: tuple[int, ...] = ()

The alternative damage values the SRD prints when the referee decides between them.

An insect swarm does 2 or 4 damage depending on the target's armour, and the referee picks one. Empty for every other attack.

by_weapon class-attribute instance-attribute

by_weapon: bool = False

True when the monster attacks with whatever weapon it has, so damage is the SRD's typical value rather than a fixed property of the creature.

by_weapon_modifier class-attribute instance-attribute

by_weapon_modifier: int = 0

The bonus or penalty the SRD prints with a by-weapon attack, like a bugbear's +1 to damage.

effects class-attribute instance-attribute

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

What a hit does beyond damage, as tags like "poison", "paralysis", or "energy_drain".

For the numbers behind a tag, call MonsterTemplate.ability with the same tag. It returns None when the template has no ability with that tag.

MonsterCatalog

Bases: BaseModel

A set of monster templates with lookup by id.

load_monsters returns the built-in catalog. It validates the data on the first call and returns the same object on every later call. Look a monster up by id with get, or iterate monsters to filter by Hit Dice, category, or anything else you need for an encounter table.

Constructing one raises pydantic.ValidationError when two templates have the same id. Frozen.

monsters instance-attribute

monsters: tuple[MonsterTemplate, ...]

The templates, each with a different id. The built-in catalog is in id order.

get

get(monster_id: str) -> MonsterTemplate

Return the monster with monster_id.

Parameters:

Name Type Description Default
monster_id str

The id to look up, like "troll" or "red_dragon". Each template's id in monsters is one, and the monster id index lists the built-in ids.

required

Returns:

Type Description
MonsterTemplate

The monster template. Spawn a creature from it with spawn_monster.

Raises:

Type Description
ValueError

If no monster has that id. The message includes the id you passed. Check the spelling against the monster id index.

Examples:

from osrlib.data import load_monsters

catalog = load_monsters()
troll = catalog.get("troll")
print(troll.name, troll.hit_dice.count, troll.xp)
# Troll 6 650
centipede = catalog.get("centipede_giant")
print(f"{centipede.name} / {centipede.display_name}")
# Centipede, Giant / giant centipede

family

family(family_id: str) -> tuple[MonsterTemplate, ...]

Return every form of one creature: the templates whose family_id is family_id.

Use it when you know what kind of creature a group is and not which form, as a client does that reads EncounterGroupView.family_id. For example, read the forms' Hit Dice to tell the players how dangerous a hellhound can be.

Parameters:

Name Type Description Default
family_id str

A template's family_id, like "hellhound" or "goblin".

required

Returns:

Type Description
tuple[MonsterTemplate, ...]

The templates of that family, in the order of monsters. A creature with one form gives a tuple of one template.

Raises:

Type Description
ValueError

If no template has that family id. The message includes the id you passed.

Examples:

from osrlib.data import load_monsters

catalog = load_monsters()
hellhounds = catalog.family("hellhound")
print([template.id for template in hellhounds])
# ['hellhound_3', 'hellhound_4', 'hellhound_5', 'hellhound_6', 'hellhound_7']
print(hellhounds[0].display_name, hellhounds[0].display_name_plural)
# hellhound hellhounds
print([template.id for template in catalog.family("goblin")])
# ['goblin']

MonsterHitDice

Bases: BaseModel

A monster's Hit Dice, as the stat block prints them.

Read it as MonsterTemplate.hit_dice. spawn_monster rolls hit points from it, and osrlib.core.tables uses it to place the monster on the attack matrix and in an experience band. The SRD's 6+3* is a count of 6, a modifier of 3, and one asterisk.

Constructing one raises pydantic.ValidationError when die is not 8 or 4, or when count is 0 and fixed_hp is None. Frozen.

count class-attribute instance-attribute

count: int = Field(default=0, ge=0)

How many dice are rolled. 0 for a creature whose hit points are fixed.

die class-attribute instance-attribute

die: int = 8

The size of each die: 8, or 4 for a creature with half a Hit Die, which rolls 1d4.

modifier class-attribute instance-attribute

modifier: int = 0

Hit points added to the rolled total, or taken from it when negative. The SRD's 1-1 is a modifier of −1.

A positive modifier also makes the creature attack as though it had one more Hit Die, and moves it to the higher + row of its experience band. A negative modifier drops it a row.

asterisks class-attribute instance-attribute

asterisks: int = Field(default=0, ge=0)

How many asterisks the SRD prints after the Hit Dice, one per special ability. Each one raises the experience award.

average_hp class-attribute instance-attribute

average_hp: int | None = None

The average hit points the SRD prints, for a referee who would rather not roll. spawn_monster ignores it and rolls.

fixed_hp class-attribute instance-attribute

fixed_hp: int | None = None

Hit points that are not rolled, like a normal bat's 1 or a hydra's 8 per head. None when they're rolled.

MonsterInstance

Bases: BaseModel

One creature in play, spawned from a frozen MonsterTemplate.

Get one from spawn_monster. An instance is what takes damage, gains conditions, and dies. The template it came from never changes, and what happens to one instance doesn't affect the other creatures spawned from the same template.

An instance has the same rules attributes as a Character: THAC0, attack bonus, both armour classes, saving throws, conditions, and stat modifiers. The functions in osrlib.core.combat and osrlib.core.effects therefore accept either one, through the protocols in osrlib.core.creature.

The instance doesn't copy what the template defines. Read that through template. For the values a drain changes, read the instance's properties, like thac0 and saves, rather than the template's fields.

An instance isn't frozen. Each assignment to a field is validated. A value that breaks a rule, like a negative current_hp or a current_hp above max_hp, raises pydantic.ValidationError, and every field still has the value it had before the assignment.

id instance-attribute

id: str

The entity id, usually from IdAllocator.allocate. Events refer to the creature by it.

template instance-attribute

template: MonsterTemplate

The stat block this creature was spawned from. Read anything the creature shares with its kind from here.

max_hp class-attribute instance-attribute

max_hp: int = Field(ge=1)

The hit points it was spawned with, 1 or more.

current_hp class-attribute instance-attribute

current_hp: int = Field(ge=0)

The hit points it has left, from 0 up to max_hp.

deal_damage stops it at 0 and applies the dead condition through kill. Healing stops it at max_hp.

conditions class-attribute instance-attribute

conditions: tuple[ActiveCondition, ...] = ()

The conditions on it. Apply and clear them through osrlib.core.effects.

stat_modifiers class-attribute instance-attribute

stat_modifiers: tuple[ActiveModifier, ...] = ()

Timed bonuses and penalties on it, from spells and effects.

alignment class-attribute instance-attribute

alignment: Alignment | None = None

The alignment this creature has, set when it was spawned.

None when the template offered several alignments with no usual one, and you passed none to spawn_monster. A ward that depends on alignment treats such a creature as being of a different alignment, so the ward protects the party.

nonregen_damage class-attribute instance-attribute

nonregen_damage: int = Field(default=0, ge=0)

Damage a regenerating creature can never heal, up to max_hp.

Damage of an element in the blocked_by param of the template's regeneration ability counts here, which is fire and acid for a troll. A troll stays dead only once this damage alone reaches its maximum hit points.

last_damaged_round class-attribute instance-attribute

last_damaged_round: int | None = None

The combat round in which it was last hurt, from which the regeneration delay is counted. None before anything has hurt it.

breath_uses_today class-attribute instance-attribute

breath_uses_today: int = Field(default=0, ge=0)

How many times it has used its breath weapon today.

resolve_breath adds 1 each time when the breath has a daily limit. The limit is the uses_per_day param of the template's breath_weapon ability, which is 3 for a dragon. A breath weapon with no uses_per_day has no daily limit.

drained_hd class-attribute instance-attribute

drained_hd: int = Field(default=0, ge=0)

How many Hit Dice have been drained from it, which drain_monster_hd adds to. Its THAC0, attack bonus, and saving throws follow the Hit Dice it has left.

name property

name: str

The creature's printed name, the template's name, like "Centipede, Giant".

To name the creature to the players in a sentence, use the template's display_name.

hit_dice_count property

hit_dice_count: int

How many Hit Dice this creature still has: the template's count less drained_hd, never below 0.

Its THAC0, attack bonus, and saving throws all follow from this rather than from the template, so draining a creature weakens it in every way at once.

thac0 property

thac0: int

The d20 roll this creature needs to hit armour class 0 under descending armour class.

For a creature that hasn't been drained, it's the template's printed value. That value already includes the rule that a creature with a positive Hit Dice modifier attacks as though it had one more Hit Die. For a drained creature, the value is looked up again for the Hit Dice it has left, with the same rule.

attack_bonus property

attack_bonus: int

The bonus this creature adds to an attack roll under ascending armour class.

It is the ascending form of thac0, and a drain changes it the same way.

armour_class property

armour_class: int | None

The creature's armour class, where lower is better. None for a creature no attack roll is made against.

armour_class_ascending property

armour_class_ascending: int | None

The creature's armour class, where higher is better. None for a creature no attack roll is made against.

saves property

saves: SavingThrows

The five saving throw targets for this creature.

For a creature that hasn't been drained, these are the template's printed values. A drained creature saves as a monster with the Hit Dice it has left, from the monster saving throw table.

melee_modifier property

melee_modifier: int

Always 0, because monsters have no STR score and the SRD gives them no melee bonus in its place.

The combat functions read this property on a monster the same way they read it on a Character.

missile_modifier property

missile_modifier: int

Always 0, because monsters have no DEX score and the SRD gives them no missile bonus in its place.

initiative_modifier property

initiative_modifier: int

Always 0, because the SRD gives a monster no initiative modifier.

To give a monster one, pass it as monster_modifier to participant_modifier.

MonsterSaves

Bases: BaseModel

A monster's saving throws, and the stat block's entry for which class and level it saves as.

Read it as MonsterTemplate.saves. To get the values adjusted for a creature that has been drained of Hit Dice, read MonsterInstance.saves instead. Frozen.

values instance-attribute

values: SavingThrows

The five saving throw targets. See SavingThrows.

save_as instance-attribute

save_as: str

The stat block's save-as entry, like "2" for a 2nd-level fighter, "NH" for a normal human, or "Cleric 1".

Show it, or use it to check values against the SRD's tables. osrlib uses only values.

MonsterTemplate

Bases: BaseModel

A monster's stat block: everything true of every creature of that kind.

Get one from load_monsters().get(monster_id). The monster id index lists the ids. Then call spawn_monster to put a creature into play. To write a monster of your own, construct one, and pass it to spawn_monster the same way.

A template is frozen, and play never changes it. Every creature of its kind shares it. The hit points one creature has left, the wounds it has taken, and the conditions on it are on the MonsterInstance spawned from it, so a wounded troll doesn't weaken every other troll in the dungeon.

Constructing one raises pydantic.ValidationError when attack_roll_required is True and either armour class is None, or when it is False and either armour class is set.

id instance-attribute

id: str

The monster id, like "troll".

Pass it to MonsterCatalog.get to look the template up.

name instance-attribute

name: str

The creature's name as the SRD prints it, like "Centipede, Giant" or "Veteran (2)".

Many of the SRD's names are written for a rulebook's index. To name the creature to the players, use display_name.

display_name class-attribute instance-attribute

display_name: str = Field(default='', validate_default=True)

What to call one of these creatures in a sentence, like "giant centipede".

It's lowercase unless a word is a proper noun, so capitalize the first letter where it starts a line. It leaves out what the players can't see. "Veteran (2)", a 2nd-level veteran, is "veteran", and "Hellhound (5)", a hellhound with 5 Hit Dice, is "hellhound". The session gives a group of these creatures this name as its label.

A template you write that leaves it out gets its name.

display_name_plural class-attribute instance-attribute

display_name_plural: str = Field(default='', validate_default=True)

What to call two or more of these creatures, like "giant centipedes" or "wolves".

A template you write that leaves it out gets display_name with the regular English ending: s, or es after s, x, z, ch, or sh, or ies in place of a y that follows a consonant. Set it yourself when the plural is irregular.

family_id class-attribute instance-attribute

family_id: str = Field(default='', validate_default=True)

The id this template shares with the other forms of the same creature, like "hellhound".

The SRD gives some creatures several stat blocks, and each one is a template. A veteran of each level is a template, veteran_1 to veteran_3, and the family of all three is "veteran". The players see a veteran and can't see its level, so the player view reports a group's family and not its template, in EncounterGroupView.family_id. Pass a family id to MonsterCatalog.family to get every form.

A creature with one form is a family of one, and its family id is its id. A template you write that leaves this out gets its id too.

page instance-attribute

page: str

The file name of the SRD page this template was compiled from, like "Hydra.md".

Templates with the same page describe related creatures, like the sizes of hydra or the colours of dragon. The sizes of hydra are forms of one creature and the colours of dragon aren't, so to find the forms of one creature, use family_id.

intro class-attribute instance-attribute

intro: str = ''

The SRD's description of the creature, for a referee or a narrator to read out.

ac class-attribute instance-attribute

ac: int | None = None

Armour class in the descending presentation, where lower is better.

None for a creature that every attack hits without a roll, when attack_roll_required is False.

ac_ascending class-attribute instance-attribute

ac_ascending: int | None = None

The same armour class in the ascending presentation, where higher is better. None when ac is.

ac_alternates class-attribute instance-attribute

ac_alternates: tuple[AcAlternate, ...] = ()

Armour classes that apply only in particular circumstances. See AcAlternate.

attack_roll_required class-attribute instance-attribute

attack_roll_required: bool = True

False for a creature that every attack hits without a roll, like a green slime. Both armour class fields are None then.

hit_dice instance-attribute

hit_dice: MonsterHitDice

The dice its hit points are rolled on. See MonsterHitDice.

attacks class-attribute instance-attribute

attacks: tuple[AttackRoutine, ...] = ()

The sets of attacks it can make, one set per round. See AttackRoutine.

thac0 class-attribute instance-attribute

thac0: int = Field(ge=2, le=20)

Its THAC0 ("to hit armour class 0"): the d20 roll it needs to hit armour class 0 under descending armour class.

To read the value for a creature that has been drained of Hit Dice, use MonsterInstance.thac0.

attack_bonus class-attribute instance-attribute

attack_bonus: int = Field(ge=-1)

The bonus it adds to a d20 attack roll under ascending armour class. It is the same attack skill as thac0.

movement class-attribute instance-attribute

movement: tuple[MovementMode, ...] = Field(min_length=1)

How it gets around and how fast, ordinary movement first. See MovementMode.

saves instance-attribute

saves: MonsterSaves

Its saving throws. See MonsterSaves.

morale class-attribute instance-attribute

morale: int | None = Field(default=None, ge=2, le=12)

How willing it is to keep fighting, from 2 to 12. A morale check is a 2d6 roll, and the creature holds on a result at or under the score. Pass it to check_morale. None when the stat block prints no morale score.

morale_alternates class-attribute instance-attribute

morale_alternates: tuple[MoraleAlternate, ...] = ()

Morale scores that apply only in particular circumstances. See MoraleAlternate.

alignment instance-attribute

alignment: AlignmentSpec

Which alignments it may have. See AlignmentSpec.

xp class-attribute instance-attribute

xp: int = Field(ge=0)

The experience for defeating one, as the SRD prints it.

xp_notes class-attribute instance-attribute

xp_notes: tuple[XpNote, ...] = ()

What a leader or other special member of a group is worth instead of xp. See XpNote.

number_appearing instance-attribute

number_appearing: NumberAppearing

How many appear, which depends on where they are met. See NumberAppearing.

treasure class-attribute instance-attribute

treasure: TreasureRef = TreasureRef()

What treasure they have. See TreasureRef.

abilities class-attribute instance-attribute

abilities: tuple[MonsterAbility, ...] = ()

What it can do beyond its attacks. See MonsterAbility.

defenses class-attribute instance-attribute

defenses: Defenses = Defenses()

What it resists, in the form the damage rules check. See Defenses.

categories class-attribute instance-attribute

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

What kind of creature it is, as tags like "undead", "person", and "enchanted".

Spells and turning check these. Hold person affects a monster only when it has "person", and turning affects only "undead".

overrides_applied class-attribute instance-attribute

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

The field paths, like "categories", that a correction changed when this template was compiled from the SRD.

Empty when the SRD page compiled without corrections. Read it when you check osrlib's data against the SRD. osrlib doesn't read it during play.

ability

ability(tag: str) -> MonsterAbility | None

Return this monster's ability with tag, or None when it has none.

Use it to find out whether a creature has a power and to read the numbers behind it in one step: the troll's regeneration rate, the number of levels a wight's touch drains, the shape and element of a dragon's breath.

Parameters:

Name Type Description Default
tag str

The ability tag to look for, like "regeneration" or "energy_drain".

required

Returns:

Type Description
MonsterAbility | None

The first ability in abilities with that tag, or None. Read its params for the numbers.

Examples:

from osrlib.data import load_monsters

wight = load_monsters().get("wight")
drain = wight.ability("energy_drain")
print(drain.params["levels"], drain.params["xp_policy"])
# 1 halfway
print(wight.ability("breath_weapon"))
# None

MoraleAlternate

Bases: BaseModel

A morale score that applies only in a particular situation.

Read them from MonsterTemplate.morale_alternates. A creature that fights bravely except when fire is involved has its usual score in the template's morale and the exception here.

The functions in osrlib.core never apply these, because deciding whether the situation holds is the referee's call. In a game session's battle, the osrlib.crawl package uses an alternate whose condition mentions fire once the group has taken fire damage. Frozen.

score class-attribute instance-attribute

score: int = Field(ge=2, le=12)

The morale score in this situation, from 2 to 12. A morale check is a 2d6 roll, and the creature holds on a result at or under the score.

condition class-attribute instance-attribute

condition: str = Field(min_length=1)

When it applies, in the SRD's words, like "in melee" or "fear of fire".

MovementMode

Bases: BaseModel

One way a monster moves, and how fast.

Read them from MonsterTemplate.movement. The first is the rate the stat block prints first, which is the creature's main way of moving. Later ones are its other ways of moving, and you pick the one the situation calls for. Frozen.

rate_feet class-attribute instance-attribute

rate_feet: int = Field(ge=0)

Feet covered in one exploration turn of 10 minutes, the rate used while mapping and searching.

encounter_rate_feet class-attribute instance-attribute

encounter_rate_feet: int = Field(ge=0)

Feet covered in one combat round, a third of rate_feet, rounded down.

descriptor class-attribute instance-attribute

descriptor: str | None = None

How the creature is moving, in the SRD's word: "flying", "swimming", "in webs". None for walking.

NumberAppearing

Bases: BaseModel

How many of a creature appear, which depends on where they are met.

Read it as MonsterTemplate.number_appearing, and roll the value that matches the encounter. Frozen.

dungeon instance-attribute

How many appear when they are met wandering in a dungeon.

lair instance-attribute

How many appear in their lair or in the wilderness, where they are usually found in larger numbers.

NumberAppearingValue

Bases: BaseModel

How many of a creature appear, as either dice to roll or a flat number.

Read it from NumberAppearing.dungeon or NumberAppearing.lair. Exactly one of the three fields applies. When dice is set, roll it with roll. When fixed is set, use it. When see_below is True, read the number from the creature's description.

Constructing one raises pydantic.ValidationError when dice is not a valid dice expression, or when the fields don't set exactly one of the three. Frozen.

dice class-attribute instance-attribute

dice: str | None = None

The dice to roll, like "1d8". None when the count is fixed or given in prose.

fixed class-attribute instance-attribute

fixed: int | None = None

A flat count. None when the count is rolled or given in prose.

see_below class-attribute instance-attribute

see_below: bool = False

True when the SRD gives no number here and the creature's description gives it instead. dice and fixed are both None then.

RoutineUse

Bases: StrEnum

When a monster may use one of its attack routines, taken from the monster's OSE SRD entry.

Each AttackRoutine has one of these values in its use field. There are four values:

  • PRIMARY: the first routine the stat block prints.
  • ALTERNATIVE: a routine the monster may use instead of the first in any round.
  • SITUATIONAL: a routine for a situation osrlib doesn't model, like a charge or a ship.
  • SPECIAL: a breath, a gaze, or a spell, which battle never rolls as an attack.

The first routine of every built-in template is PRIMARY, and each later routine has one of the other three values. In battle, an ActionPolicy chooses what each monster does in a round. It reads this value to decide whether it may pick the routine for a round of melee. The default policy, ScriptedPolicy, picks with equal chance among a monster's PRIMARY and ALTERNATIVE routines. A policy of your own can pick any routine by its index in MonsterAction.routine.

PRIMARY class-attribute instance-attribute

PRIMARY = 'primary'

The first routine the stat block prints. Battle uses it when a policy picks no routine.

ALTERNATIVE class-attribute instance-attribute

ALTERNATIVE = 'alternative'

A routine the monster may use in place of the first in any round, as the SRD's "or" offers.

A thoul claws or uses a weapon, and a mule kicks or bites. The default policy picks it as often as the first routine.

SITUATIONAL class-attribute instance-attribute

SITUATIONAL = 'situational'

A routine the SRD ties to a situation osrlib doesn't model. The default policy never picks it.

The situation can be a range, a charge, a chance to trample, water, a ship, a form, or what the monster carries. Examples are an elephant's trample, a giant's thrown boulder, and a sperm whale's ram against a ship. A policy of your own can name the routine when your game decides the situation applies. Battle then rolls its attacks as melee attacks.

SPECIAL class-attribute instance-attribute

SPECIAL = 'special'

A routine battle never rolls as an attack: a breath, a gaze, or a spell.

A dragon breathes through a "breath" action. A petrifying gaze takes effect once a round, before the gazer's group acts. The referee handles the rest. If a policy picks this routine in a "melee" action, the monster rolls nothing that round.

TreasureRef

Bases: BaseModel

What treasure a monster has, as the stat block prints it.

Read it as MonsterTemplate.treasure, then pass it to plan_treasure_ref. That function sorts the letters into lair, per-creature, and per-group treasure, and returns extra_gp and multiplier with them. Generate each letter in the plan with generate_treasure. Each letter is the letter of one table in load_treasure_tables().treasure_types, and the treasure type index lists them.

Use the plan rather than passing each of letters to generate_treasure yourself. A loop over letters drops the bracketed letters, the extra gold, and the multiplier, and it treats a per-creature letter as a lair hoard.

A creature with no treasure has an empty reference. Frozen.

letters class-attribute instance-attribute

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

The treasure type letters, like ("D",).

When there is more than one, each of them is generated. plan_treasure_ref sorts them by section, so each letter goes to the lair, to each creature, or to the group, according to its table.

parenthetical class-attribute instance-attribute

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

The letters the SRD prints in brackets.

plan_treasure_ref adds them to the lair treasure, whatever section their tables are in, so a bandit's U (A) puts U on the group and A in the lair.

extra_gp class-attribute instance-attribute

extra_gp: int = Field(default=0, ge=0)

Gold pieces added to the lair hoard on top of the rolled treasure, like a cloud giant's 5,000.

multiplier class-attribute instance-attribute

multiplier: int = Field(default=1, ge=1)

How many times to generate every listed letter, as with a noble's V × 3.

1 unless the SRD prints a multiplier.

special class-attribute instance-attribute

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

Valuables that are not treasure types, like an elephant's tusks or a killer bee's honey.

osrlib doesn't generate these, so show them to the referee.

see_below class-attribute instance-attribute

see_below: bool = False

True when the creature's description, not its treasure line, gives what it has.

XpNote

Bases: BaseModel

What a leader or other special member of a group of these creatures is worth in experience.

Read them from MonsterTemplate.xp_notes. A band of gnolls has a leader worth more than the rest, and this is that number. What else makes the leader different is prose in the template's abilities, because the SRD gives it as prose. Frozen.

role class-attribute instance-attribute

role: str = Field(min_length=1)

The group member's role, like "leader", "chieftain", or "bodyguard".

xp class-attribute instance-attribute

xp: int = Field(ge=0)

The experience for defeating one.

spawn_monster

spawn_monster(
    template: MonsterTemplate, *, id: str, stream: RngStream, alignment: Alignment | None = None
) -> MonsterInstance

Put one creature into play: roll its hit points and give it an entity id.

Call it once for each creature in an encounter. You can spawn from the same template as often as you like. Each creature gets separate hit points, wounds, and conditions, and what happens to one doesn't affect the template or the other creatures spawned from it.

Pass the creature to the functions in osrlib.core.combat to fight it. For its treasure, pass the template's treasure to plan_treasure_ref. In a game session, GameSession.spawn calls this for you with the session's allocator and stream.

Hit points are one roll of each of the template's Hit Dice plus its modifier, and never less than 1. A creature whose hit points the SRD fixes, like a normal bat's 1 or a hydra's 8 per head, gets that number, and nothing is rolled.

The creature gets one alignment here, because a ward like protection from evil needs one alignment to test against. The alignment is the one you pass, or else the template's usual alignment, or else the template's only option. When the template offers several alignments with no usual one and you pass none, the creature's alignment is None. Such a ward treats it as being of a different alignment, so the ward protects the party.

Parameters:

Name Type Description Default
template MonsterTemplate

The stat block to spawn from, from load_monsters().get(monster_id). The monster id index lists the ids.

required
id str

The entity id to give it, usually allocator.allocate("monster") from an IdAllocator. Use a different id for each creature, because events refer to creatures by id.

required
stream RngStream

The stream to roll hit points on, conventionally streams.get(MONSTER_SPAWN_STREAM). It takes one draw per Hit Die, and none for a creature with fixed hit points.

required
alignment Alignment | None

The alignment to give this creature. It must be one of the template's alignment.options. None uses the template's usual or only alignment.

None

Returns:

Type Description
MonsterInstance

The creature, at full hit points, with no conditions and no wounds.

Raises:

Type Description
ValueError

If alignment is not one of the template's options. Nothing is rolled before the error. Pass one of template.alignment.options, or None.

Examples:

from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters

allocator = IdAllocator()
stream = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
template = load_monsters().get("troll")
first = spawn_monster(template, id=allocator.allocate("monster"), stream=stream)
second = spawn_monster(template, id=allocator.allocate("monster"), stream=stream)
print(first.id, first.max_hp, second.id, second.max_hp)
# monster-0001 42 monster-0002 22

first.current_hp -= 10
print(first.current_hp, second.current_hp)
# 32 22