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:
load_monstersreturns the built-inMonsterCatalog. Itsgettakes a monster id, like"troll", and returns theMonsterTemplate.IdAllocator.allocatetakes a prefix, like"monster", and returns a new entity id, like"monster-0001". Events refer to a creature by its entity id.spawn_monstertakes a template, an entity id, and the stream named byMONSTER_SPAWN_STREAM, rolls hit points, and returns aMonsterInstance.- The template's fields contain the rest of the stat block as models you read:
MonsterHitDice,AttackRoutinewithRoutineUse, andMonsterAttack,MovementMode,MonsterSaves,MoraleAlternate,AlignmentSpec,XpNote,NumberAppearingandNumberAppearingValue,TreasureRef,MonsterAbility,AcAlternate, andDefenseswithDamageKey,DamageReduction,Element, andEnergyDefense.
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
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
use: RoutineUse = RoutineUse.PRIMARY
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
A silver weapon, which harms a wight, a wraith, or a werewolf that steel can't.
FIRE
class-attribute
instance-attribute
Fire, whether from a torch, a flask of oil, or a spell.
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
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.
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
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
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, as a red dragon breathes and a fire giant ignores.
LIGHTNING
class-attribute
instance-attribute
Lightning, as a blue dragon breathes.
POISON
class-attribute
instance-attribute
Poison that isn't a gas, as a sea dragon spits.
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
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
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 |
required |
Returns:
| Type | Description |
|---|---|
str
|
The id, which is the prefix, a hyphen, and a number padded to at least four digits,
counting from |
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
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 itsparamshavemeets_gaze. Every character the monster surprises is then affected by its gaze, as with a basilisk.attacks_othersin theparamsof 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
The ability's name as the SRD prints it, for display.
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
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
How many of this attack the monster makes in a round.
name
class-attribute
instance-attribute
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
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
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 |
required |
Returns:
| Type | Description |
|---|---|
MonsterTemplate
|
The monster template. Spawn a creature from it with
|
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:
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 |
required |
Returns:
| Type | Description |
|---|---|
tuple[MonsterTemplate, ...]
|
The templates of that family, in the order of |
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
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
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
The hit points it was spawned with, 1 or more.
current_hp
class-attribute
instance-attribute
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
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
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
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.
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
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
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
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
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
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.
morale
class-attribute
instance-attribute
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
The experience for defeating one, as the SRD prints it.
xp_notes
class-attribute
instance-attribute
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
What it resists, in the form the damage rules check. See Defenses.
categories
class-attribute
instance-attribute
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
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 |
required |
Returns:
| Type | Description |
|---|---|
MonsterAbility | None
|
The first ability in |
Examples:
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
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.
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
Feet covered in one exploration turn of 10 minutes, the rate used while mapping and searching.
encounter_rate_feet
class-attribute
instance-attribute
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
dungeon: NumberAppearingValue
How many appear when they are met wandering in a dungeon.
lair
instance-attribute
lair: NumberAppearingValue
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
The first routine the stat block prints. Battle uses it when a policy picks no routine.
ALTERNATIVE
class-attribute
instance-attribute
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
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
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
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
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
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
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
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.
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
|
required |
id
|
str
|
The entity id to give it, usually |
required |
stream
|
RngStream
|
The stream to roll hit points on, conventionally
|
required |
alignment
|
Alignment | None
|
The alignment to give this creature. It must be one of the template's
|
None
|
Returns:
| Type | Description |
|---|---|
MonsterInstance
|
The creature, at full hit points, with no conditions and no wounds. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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