osrlib.core.creature
The attributes that rules functions read from a character or a monster instance, as protocols.
A rules function in osrlib.core.combat, osrlib.core.spells,
and osrlib.core.effects takes the creature it acts on as one of the three protocols
here, unless it needs a single concrete type, and then its entry states that. A protocol is a type that lists the
attributes a value must have, with no base class to inherit. A Character and a
MonsterInstance have those attributes, so you pass either without a
cast, and pyright checks that anything else you pass has the attributes the function reads. You don't
instantiate a protocol. Read one to learn which attributes a function reads from its argument, and annotate
your own functions with it when they take either kind of creature.
The members, from the base up:
Creature: an id, a name, an alignment, hit points, conditions, and stat modifiers.Combatant: aCreaturewith the numbers that the attack, initiative, and saving throw functions read.Caster: aCreaturewith what the functions that memorize and cast spells read.
A function that needs an attribute only one concrete type has, like a monster's template or a character's
inventory, either takes that concrete type or works without the attribute when it's missing. The function's
Args entry states which.
Typical usage:
from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
from osrlib.core.creature import Combatant, Creature
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.core.ruleset import Ruleset
from osrlib.data import load_monsters
streams = RngStreams(master_seed=7)
hero = create_character(
name="Hild",
class_id="fighter",
alignment=Alignment.LAWFUL,
ruleset=Ruleset(),
stream=streams.get(CHARACTER_CREATION_STREAM),
).character
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=streams.get(MONSTER_SPAWN_STREAM))
def hurt(creature: Creature) -> bool:
return creature.current_hp < creature.max_hp
def needs_attack_roll(combatant: Combatant) -> bool:
return combatant.armour_class is not None
print(hurt(hero), hurt(goblin), needs_attack_roll(hero), needs_attack_roll(goblin))
# False False True True
Caster
A creature that memorizes and casts spells.
memorize_spells, validate_cast,
cast_spell, and disrupt_casting
take this. A Character satisfies it and a
MonsterInstance does not, because monsters in the compiled data never
cast. The class, which sets the spell list and the number of slots, isn't part of the protocol: those functions
take the ClassDefinition or the
CasterProfile as a separate argument.
Examples:
from osrlib.core.alignment import Alignment
from osrlib.core.character import CHARACTER_CREATION_STREAM, create_character
from osrlib.core.creature import Caster
from osrlib.core.rng import RngStreams
from osrlib.core.ruleset import Ruleset
stream = RngStreams(master_seed=7).get(CHARACTER_CREATION_STREAM)
zelia = create_character(
name="Zelia",
class_id="magic_user",
alignment=Alignment.NEUTRAL,
ruleset=Ruleset(),
stream=stream,
starting_spell_ids=["sleep"],
).character
print(isinstance(zelia, Caster), zelia.level, zelia.spell_book, zelia.memorized_spells)
# True 1 ('sleep',) ()
level
instance-attribute
level: int
The caster's level, which sets the number of spell slots, a spell's range, and its effect size. A spell read from a scroll uses the scroll's level, not the reader's.
spell_book
instance-attribute
The spell ids in an arcane caster's spell book. Empty for a divine caster.
memorized_spells
instance-attribute
memorized_spells: tuple[MemorizedSpell, ...]
The prepared copies as MemorizedSpell entries, spent as they are cast.
Combatant
A creature with the numbers that the attack, initiative, and saving throw functions read.
attack_roll, resolve_attack,
saving_throw, and
participant_modifier take this. Both concrete creature types
satisfy it. Every number is read-only, because each one is computed: a character's from class, level, and
gear, a monster's from its template and any Hit Dice drained from it.
Examples:
from osrlib.core.creature import Combatant
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
stream = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=stream)
print(isinstance(goblin, Combatant), goblin.thac0, goblin.armour_class)
# True 19 6
thac0
property
thac0: int
The roll on 1d20 this creature needs to hit armour class 0 (THAC0).
osrlib looks it up in the attack matrix, and a creature with a lower THAC0 hits more often. It applies to descending armour class, where a lower armour class is better.
attack_bonus
property
attack_bonus: int
The ascending-armour-class equivalent of thac0: the bonus added to 1d20 when attacking.
armour_class
property
armour_class: int | None
Descending armour class, where lower is better.
None for a creature that attacks hit without a roll. Green slime and
yellow mould are the monsters in the compiled data with no armour class.
armour_class_ascending
property
armour_class_ascending: int | None
Ascending armour class, where higher is better. None whenever armour_class is None.
melee_modifier
property
melee_modifier: int
The bonus added to a melee attack and its damage, from strength. A monster's is 0.
missile_modifier
property
missile_modifier: int
The bonus added to a missile attack, from dexterity. A monster's is 0.
initiative_modifier
property
initiative_modifier: int
The bonus added to an individual initiative roll. A monster's is 0.
Creature
Bases: Protocol
The attributes every rules function reads from the creature it acts on.
A Character and a MonsterInstance
both satisfy this, and so does anything of your own with these attributes. Functions that read only these
attributes, like has_condition,
apply_healing, and incapacitated,
take it. A function that also reads combat numbers takes Combatant.
The hit points, conditions, and stat modifiers are writable, because rules functions change them: damage lowers
current_hp, a spell adds to conditions, an effect attaches a modifier. The id, name, and alignment are
read-only properties, so a class can supply them as plain attributes or compute them. A monster's name,
for example, comes from its template.
Examples:
from osrlib.core.creature import Creature
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
stream = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=stream)
print(isinstance(goblin, Creature), goblin.name, goblin.current_hp == goblin.max_hp)
# True Goblin True
id
property
id: str | None
The creature's entity id, or None for a character not yet in a session.
A monster gets its id when it's spawned, and a session assigns a character's. Events refer to creatures by it.
name
property
name: str
The display name: the one a character was created with, or the one from a monster's template.
alignment
property
alignment: Alignment | None
The creature's Alignment.
None for a monster spawned with no alignment chosen from a template that allows several and has no
usual one, like the bandit.
current_hp
instance-attribute
current_hp: int
Hit points now. Rules functions lower and raise it in place.
max_hp
instance-attribute
max_hp: int
The most hit points the creature can have. Healing stops here.
conditions
instance-attribute
conditions: tuple[ActiveCondition, ...]
The active ActiveCondition entries, in the order they were granted.
Read them through has_condition.
stat_modifiers
instance-attribute
stat_modifiers: tuple[ActiveModifier, ...]
The active ActiveModifier entries. Read them through
modifier_total and its siblings.