Skip to content

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: a Creature with the numbers that the attack, initiative, and saving throw functions read.
  • Caster: a Creature with 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

Bases: Creature, Protocol

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

spell_book: tuple[str, ...]

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

Bases: Creature, Protocol

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.

saves property

saves: SavingThrows

The five saving-throw targets as SavingThrows.

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.