osrlib.core.effects
Attach timed effects to creatures and locations, and run them against the game clock.
An effect is anything in play that lasts a while or repeats: a sleep spell, a poison, a burning torch, a troll's
regeneration. You describe one with an EffectDefinition, attach it to a target
through an EffectsLedger, and move time forward by passing a
GameClock to the ledger's advance method. The ledger ends each effect when its
duration runs out, and runs its periodic behavior along the way.
Three kinds of code call this module. A GameSession calls
EffectsLedger.advance every time it moves the game clock.
cast_spell calls EffectsLedger.attach
when a spell takes effect, so the spell's duration becomes a live effect. You call both yourself when you run the
rules without a session. You then keep the ledger, the GameClock, and the
registry, and you advance them in your own loop.
The members, in the order you use them:
EffectDefinition: the blueprint you write, with a duration, a condition, modifiers, a periodic tick, and an outcome at expiry.ModifierSpec: one stat adjustment a definition grants. Itskindis one ofMODIFIER_KINDS.regeneration_definition: takes a regenerating monster's ability params and returns a ready-made definition.EffectsLedger: the object that tracks and runs effects. Itsattachmethod takes a definition and returns anActiveEffect. Itsadvancemethod moves the clock and returns the events of everything that expired or ticked. Itsreleasemethod ends an effect early, and itsactive_onmethod lists the effects on one target.EFFECTS_STREAM: the name of the random-number stream thatattachandadvancedraw from.Conditionandhas_condition: the named states a creature can be in, and the check for one.grant_condition,remove_condition, andkill: put on or take off a condition that doesn't come from a timed effect.ActiveConditionandActiveModifier: the records of a condition and a modifier on a creature.modifier_total,modifier_values,modifier_dice, andhas_modifier: take a creature and a modifier kind, and return the adjustment that applies.
A condition is a named state a creature is in, like asleep or petrified. Each creature has a conditions
tuple of ActiveCondition records and a stat_modifiers tuple of
ActiveModifier records. A serialized creature therefore shows what is
wrong with it without the ledger beside it. The combat functions read both tuples through
has_condition and the modifier functions.
The ledger writes a creature's conditions and modifiers when an effect attaches, and takes them back when the
effect ends. Only grant_condition,
remove_condition, and kill write them
apart from the ledger, for the states that don't come from a timed effect. Use those functions rather than
assigning to creature.conditions. A condition you assign yourself has no effect behind it, so the ledger never
takes it back.
Each round that EffectsLedger.advance passes through resolves in
a fixed order. First, the ledger suspends the effects on a creature that another effect has petrified. Then
expirations resolve, and then ticks. Within each phase, effects resolve in attachment order, and effect id breaks
a tie. A suspended effect neither ticks nor ages while the stone lasts, so an adventurer who was poisoned before
being turned to stone is still poisoned after stone to flesh.
The random draws for effects, like rolled durations, charm saves, splash damage, and a troll's revival
countdown, come from the stream named by EFFECTS_STREAM. An extra
draw in combat therefore never shifts an effect's roll.
The target parameters in this module take a Creature, the protocol for the
hit points, conditions, and stat modifiers these calls read. A Character
and a MonsterInstance both satisfy it. A registry is a mapping from
entity id to those creatures, like {"monster-0001": goblin}. A session builds one with
GameSession.registry.
Typical usage:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EFFECTS_STREAM, Condition, EffectDefinition, EffectsLedger, has_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=3)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=streams.get(MONSTER_SPAWN_STREAM))
registry = {"monster-0001": goblin}
ledger = EffectsLedger()
clock = GameClock()
sleep = EffectDefinition(
kind="sleep",
duration_unit=TimeUnit.TURN,
duration_amount=4,
condition=Condition.ASLEEP,
dispellable=True,
)
effect, events = ledger.attach(sleep, "monster-0001", clock=clock, allocator=IdAllocator(), registry=registry)
assert [event.code for event in events] == ["effects.effect.attached", "effects.condition.gained"]
assert has_condition(goblin, Condition.ASLEEP)
# Four turns later the duration runs out and the ledger takes the condition back.
expiry = ledger.advance(clock, 4, TimeUnit.TURN, registry, stream=streams.get(EFFECTS_STREAM))
assert [event.code for event in expiry] == ["effects.effect.expired", "effects.condition.removed"]
assert not has_condition(goblin, Condition.ASLEEP)
assert ledger.effects == []
EFFECTS_STREAM
module-attribute
EFFECTS_STREAM = StreamName.EFFECTS
The name of the random-number stream that effects draw from, for rolled durations, ticks, and expiry outcomes.
Build an RngStreams from your master seed and pass streams.get(EFFECTS_STREAM)
wherever EffectsLedger.attach and
EffectsLedger.advance take a stream. A
GameSession does this for you. Each subsystem draws from a separate named
stream, so an extra attack roll never changes the round on which a charmed creature saves and breaks free.
MODIFIER_KINDS
module-attribute
MODIFIER_KINDS = frozenset(
{
"attack_bonus",
"damage_bonus",
"morale_bonus",
"save_bonus",
"ac_bonus",
"ac_set",
"ac_set_vs_missile",
"attack_penalty_of_attackers",
"damage_reduction_per_die",
"damage_multiplier",
"melee_damage_multiplier",
"missile_immunity_nonmagical",
"strength_set",
"weapon_damage_dice_bonus",
"counts_as_magical",
"magical_healing_half",
}
)
The closed set of statistic names a modifier can adjust.
These are the only values a ModifierSpec accepts for its kind. A
ModifierSpec with any other name raises pydantic's ValidationError when you construct it. The combat code
looks up each kind by name while it resolves a roll, and a kind it didn't look up would change nothing. When you author
content of your own, express each adjustment with a kind in this set.
In the list below, the bearer is the creature the modifier is on. What each kind does:
attack_bonusadjusts the bearer's attack rolls, anddamage_bonusits damage rolls.attack_penalty_of_attackersadds its value to the attack rolls of anyone attacking the bearer. A ward like protection from evil uses a negative value.save_bonusadjusts the bearer's saving throws, narrowed byelement,save_categories, orversus_other_alignment.morale_bonusadjusts the bearer's side's morale checks throughmorale_modifier.ac_bonusimproves the bearer's armour class by its value.ac_setreplaces the bearer's armour class against attacks that aren't missiles, when the set value is better.ac_set_vs_missiledoes the same against missile attacks, and against a missile only it counts. That's how shield gives one armour class against missiles and another against everything else.damage_reduction_per_dietakes points off incoming damage, one per die rolled, for the namedelement.damage_multipliermultiplies the bearer's weapon damage, andmelee_damage_multiplierits melee damage, after the flat bonuses are added. A value of 1 or less changes nothing.weapon_damage_dice_bonusadds the modifier'sdiceto the bearer's weapon damage.strength_setreplaces the strength score that the bearer's melee modifier, chance to force a stuck door, and will in a sentient sword's contest come from, asCharacter.effective_strengthreports it. That's how Gauntlets of Ogre Power give a fixed 18 and a Ring of Weakness a fixed 3.counts_as_magicalmakes the bearer's attacks count as magical, so they can harm a monster that only magic can hurt.missile_immunity_nonmagicalmakes the bearer immune to non-magical missiles.magical_healing_halfhalves the hit points magical healing restores to the bearer.
ActiveCondition
Bases: BaseModel
One condition a creature currently has, paired with the effect that granted it.
You read these from a creature's conditions tuple rather than building them.
EffectsLedger.attach and
grant_condition add them. To ask whether a creature has a condition
from any effect, call has_condition instead of scanning the tuple.
Each record contains the id of the effect that granted it, so two effects can grant the same condition, and ending one effect removes only the record that effect granted. A creature charmed twice has two records, and releasing one charm leaves the other in place. Records compare by value, and a creature never has the same condition from the same effect twice.
Examples:
from osrlib.core.effects import ActiveCondition, Condition
active = ActiveCondition(condition=Condition.ASLEEP, effect_id="effect-0001")
assert active.condition is Condition.ASLEEP
assert active.model_dump(mode="json") == {"condition": "asleep", "effect_id": "effect-0001"}
effect_id
class-attribute
instance-attribute
effect_id: str | None = None
The id of the ActiveEffect that granted the condition and will take
it back. None marks a condition that doesn't come from a timed effect. In osrlib, that's dead.
ActiveEffect
Bases: BaseModel
One effect currently running on a creature or a location.
EffectsLedger.attach creates one, adds it to the ledger's
effects list, and returns it. EffectsLedger.active_on finds
it again. Read it to see how long the effect has left or what it is tracking. Pass its effect_id to
EffectsLedger.release to end it early. You don't build these
yourself. When load_game restores a ledger from a save, it rebuilds them.
effect_id
instance-attribute
effect_id: str
The effect's id, like effect-0001, from the IdAllocator you
passed to attach. The conditions and modifiers the effect granted contain this id, which is how the ledger
finds them when the effect ends.
definition
instance-attribute
definition: EffectDefinition
The EffectDefinition the effect was attached from. The ledger
ticks and expires the effect from this copy, so a saved ledger needs nothing else.
target_ref
instance-attribute
target_ref: str
What the effect is on. It's an entity id for a creature, or a location string, like one from
cell_ref, for an effect that stays in a place, like a pool of burning oil.
A location string isn't a key in the registry, so an effect on a location grants no conditions or
modifiers.
attached_round
class-attribute
instance-attribute
The round the effect was attached on, counted from the start of the game clock. The effect ticks every
tick_interval_rounds from this round. When several effects resolve in one round, they go in order of this
value first, then in the order they were attached, which is their order in
EffectsLedger.effects.
expires_round
class-attribute
instance-attribute
expires_round: int | None = None
The round the effect expires on, counted from the start of the game clock, or None when it has no
duration or is permanent. While the bearer is petrified by another effect, this moves forward one round for
each round that passes. A suspended effect therefore has the same time left when the stone is undone.
caster_level
class-attribute
instance-attribute
caster_level: int | None = None
The level of the caster whose spell attached this effect, or None when attach got no caster_level.
When dispel magic tries to end the effect, osrlib rolls against it to decide whether the effect survives.
state
class-attribute
instance-attribute
The effect's running counters, like revive_at, the round a dead troll gets up on, or rest_days, the
rest days counted so far for a slowed-healing effect. The ledger and
natural_healing write it. Read it to show a countdown.
ActiveModifier
Bases: ModifierSpec
One live modifier on a creature, paired with the effect that granted it.
These are the entries of a creature's stat_modifiers tuple. Attaching an effect turns each
ModifierSpec in its definition into one of these. When the effect
expires or is released, the ledger removes them again, the same way it removes conditions. Nothing else in
osrlib writes the tuple, so each modifier on a creature belongs to an effect on the ledger.
Read them through modifier_total rather than scanning the tuple,
because it applies the scope fields and the rule that spell bonuses don't add up.
modifier_values, modifier_dice,
and has_modifier cover the other ways the combat code reads them.
effect_id
instance-attribute
effect_id: str
The id of the ActiveEffect that granted the modifier and will take
it back.
Condition
Bases: StrEnum
The closed set of named states a creature can be in, like asleep, charmed, or dead.
Check whether a creature has a condition with has_condition. To put
one on a creature for a while, set it as an EffectDefinition's
condition and attach the definition with EffectsLedger.attach.
The ledger then takes the condition away when the duration runs out. Use
grant_condition only for a state that doesn't come from a timed effect.
Some members change rolls and actions in osrlib.core.combat and
osrlib.core.spells. Others matter only to the crawl procedures in
osrlib.crawl or to your own code. Each member's description lists where osrlib reads it, so
you know whether granting it changes a roll or only what your interface shows.
Immunity applies to every member. A monster whose template lists a condition in its defenses'
condition_immunities never takes that condition, whether you call
grant_condition or attach an effect that brings it. So even when no
other core rule reads a member, immunity limits which monsters a spell can affect.
The values are the lowercase strings, like "asleep", and creatures and saved games contain them. A value
changes only with a schema_version bump.
PARALYSED
class-attribute
instance-attribute
Frozen in place. The creature can't attack, cast, or move. It counts as incapacitated for the morale check
that morale_triggers raises when half a side is out of the fight. A
melee attack against it hits automatically. Cure light wounds cures it.
ASLEEP
class-attribute
instance-attribute
Unconscious. Like paralysed, the creature can't attack, cast, or move, it counts as incapacitated for
morale, and a melee attack against it hits automatically. A melee hit with a bladed weapon also kills the
sleeper outright, with no damage roll. Cure light wounds doesn't cure it.
BLIND
class-attribute
instance-attribute
Unable to see. validate_attack rejects the creature's attacks with
combat.attack.attacker_blind. resolve_gaze skips the creature, because it
can't see a gaze. In a battle in a GameSession, a creature that a spitting
cobra's spit hits saves versus death, and on a failed save it's blind permanently.
CHARMED
class-attribute
instance-attribute
Under a charm. The monsters that can't be charmed, the undead and the golems among them, have it in
their condition_immunities, so a charm aimed at one of those has no effect. You decide how the charmed
creature obeys. The recurring save that can end the charm is the effect's charm_resave tick.
PETRIFIED
class-attribute
instance-attribute
Turned to stone. The creature can't attack, cast, or move. A melee attack on it hits automatically, and it
counts as incapacitated for morale. The EffectsLedger suspends its other
effects, so they neither tick nor age until the stone is undone. Stone is not death. Stone to flesh cures it,
and the creature continues from where it was.
DISEASED
class-attribute
instance-attribute
Sick with a disease. Magical healing has no effect on it.
natural_healing heals it on the slower schedule the effect sets, or not
at all when you pass no ledger. Cure disease cures it.
EXHAUSTED
class-attribute
instance-attribute
Spent from running a whole pursuit. The encounter procedure in osrlib.crawl.encounter
attaches it to every living party member who escapes a pursuit that ran its full length. The penalties
come from the effect's modifiers, not from the condition. Apart from immunity, no core rule reads it, and
your interface can show it.
LYCANTHROPY_INCUBATION
class-attribute
instance-attribute
Infected by a lycanthrope's bite and not yet transformed. Nothing in osrlib grants it, and apart from immunity no core rule reads it. You run the transformation yourself.
AVERTED_EYES
class-attribute
instance-attribute
Fighting with eyes turned away from a gaze attack. resolve_gaze skips
the creature. Pass the attack penalty for fighting blind yourself, in the attack context. A battle in a
GameSession does this for you. It grants the condition for one round to a
member whose gaze_defense is avert_eyes, and applies
the penalty and the gazer's bonus.
POISONED
class-attribute
instance-attribute
Poisoned. The monsters that can't be poisoned, the undead and the cave locust among them, have it in
their condition_immunities, so a poison aimed at one of those has no effect. Neutralize poison cures
it, and can bring back a character who died of poison within the last ten rounds. The effect does the
killing, not the condition. A poison that kills has an expiry of "death", which kills the bearer when
the effect's duration runs out.
DEAD
class-attribute
instance-attribute
Killed. kill grants it, not an effect, so its effect_id is None. A dead
creature can't act or be healed, and the battle procedure in osrlib.crawl.battle
leaves it out when it picks targets. A spell that removes the condition, like raise dead, brings the
creature back, and so does a troll's regeneration.
SILENCED
class-attribute
instance-attribute
Unable to speak. validate_cast rejects the creature's casting with
magic.cast.caster_incapacitated.
ENTANGLED
class-attribute
instance-attribute
Held fast, as by a web. cannot_move reports True, and the creature
can still attack and cast.
AFRAID
class-attribute
instance-attribute
Panicked by a fear effect. Remove fear cures it. When the fear is magical, the subject first saves versus
spells at +1 for each level of the curing caster, and keeps the fear if the save fails. The battle procedure in
osrlib.crawl.battle counts a monster group as routed when every living member is
afraid or turned.
FEEBLEMINDED
class-attribute
instance-attribute
Unable to think clearly enough to cast. validate_cast rejects the
creature's casting with magic.cast.caster_incapacitated.
INVISIBLE
class-attribute
instance-attribute
Unseen. Apart from immunity, no core rule reads it. The battle procedure in
osrlib.crawl.battle leaves the creature out of the ranks an enemy picks targets
from, and rejects a spell declared at it with battle.declaration.invisible_target.
TURNED
class-attribute
instance-attribute
Driven off by a cleric's turning. turn_undead attaches the effect
that grants it. Apart from immunity, no core rule reads it. The battle and encounter procedures in
osrlib.crawl.battle and osrlib.crawl.encounter treat
the creature as fleeing.
CONFUSED
class-attribute
instance-attribute
Acting at random. Apart from immunity, no core rule reads it. The battle procedure in
osrlib.crawl.battle chooses the creature's action, so you don't.
EffectDefinition
Bases: BaseModel
The blueprint for an effect: how long it lasts, what it does while it lasts, and what happens when it ends.
Write one of these for each spell, ability, or hazard you want to put on a creature or a place. Then pass it
to EffectsLedger.attach with the entity id or location it applies
to. Attaching creates a running ActiveEffect from the blueprint. The
blueprint is frozen, so one definition serves every target you attach it to. You don't write definitions
for the spells in load_spells:
cast_spell builds and attaches those for you. Write your own when you
author something new, or run the rules without a session.
Give the effect a duration with duration_unit and either duration_amount or duration_dice. Leave all three
out and the effect runs until you release it. Set permanent, with no duration, for an effect that only magic
undoes.
Constructing one raises pydantic.ValidationError when the definition can't run:
- The duration isn't a unit with exactly one of
duration_amountandduration_dice. permanentis set and the definition has a duration.tickorexpiryisn't a name osrlib defines.- The
"splash_damage"expiry has nodiceparam.
A malformed dice expression in duration_dice, in the "splash_damage" expiry's dice param, or in the
"regeneration" tick's revive param raises ContentValidationError.
So a mistake in a definition shows up when you construct it, not when the effect attaches, ticks, or expires.
Examples:
A four-turn sleep that grants a condition, and an indefinite +1 to attacks that grants a modifier:
from osrlib.core.clock import TimeUnit
from osrlib.core.effects import Condition, EffectDefinition, ModifierSpec
sleep = EffectDefinition(
kind="sleep",
duration_unit=TimeUnit.TURN,
duration_amount=4,
condition=Condition.ASLEEP,
dispellable=True,
)
bless = EffectDefinition(kind="bless", modifiers=(ModifierSpec(kind="attack_bonus", value=1),))
assert sleep.stacking == "stack" # the default: a second sleep is a second effect
assert bless.duration_unit is None # no unit means it runs until released
kind
class-attribute
instance-attribute
The effect's name, like "sleep" or "regeneration". The model accepts any non-empty string. The ledger
compares kinds on the same target for stacking, and
EffectsLedger.active_on filters on the kind, so give each kind of
effect one name and use it everywhere.
duration_unit
class-attribute
instance-attribute
duration_unit: TimeUnit | None = None
The unit the duration is counted in: rounds, turns, or days. None means the effect has no duration and
runs until you release it. A unit needs either duration_amount or duration_dice.
duration_amount
class-attribute
instance-attribute
duration_amount: int | None = None
A fixed duration, counted in duration_unit. Use this or duration_dice, not both, and only with a unit.
duration_dice
class-attribute
instance-attribute
duration_dice: str | None = None
A dice expression rolled once at attach time to set the duration, like "2d6". The roll comes from the
effects stream, so attaching a definition with dice and no stream raises ValueError. osrlib checks the
expression with parse when you construct the definition, and a malformed one raises
ContentValidationError.
permanent
class-attribute
instance-attribute
permanent: bool = False
True means the effect never expires on its own, so a permanent definition has no duration. That's how
petrification lasts until someone casts stone to flesh. Set dispellable to choose whether dispel magic
can end the effect.
tick
class-attribute
instance-attribute
tick: Literal['regeneration', 'charm_resave'] | None = None
The name of a periodic behavior the ledger runs while the effect lasts, or None for none.
"regeneration" heals the bearer and can bring a troll back from death. "charm_resave" rolls the bearer's
saving throw versus spells and releases the effect when it passes.
tick_interval_rounds
class-attribute
instance-attribute
How many rounds pass between ticks. The default of 1 ticks every round. For a charm,
cast_spell sets it from the subject's INT: every 30 days for INT 8 or
lower, every 7 days for INT 9 to 12, and every day for INT 13 or higher. A monster has no INT score and
saves every 7 days.
stacking
class-attribute
instance-attribute
stacking: Literal['stack', 'refresh', 'ignore'] = 'stack'
What happens when you attach this kind to a target that already has an effect of the same kind.
"stack" adds a second effect. "refresh" restarts the existing effect's duration and adds nothing.
"ignore" changes nothing, and the attach returns no effect.
expiry
class-attribute
instance-attribute
expiry: Literal['death', 'splash_damage', 'weakness_strength_set'] | None = None
The name of an outcome the ledger resolves when the duration runs out, or None for none.
The outcome adds to the ordinary ending and doesn't replace it. The ledger removes the effect, emits the
EffectExpiredEvent, and takes off the condition and modifiers.
Then it runs the outcome on the bearer:
"death"kills the bearer, which is how a delayed poison works."splash_damage"deals the second round of damage from burning oil or holy water. It rolls thediceparam, which the definition needs."weakness_strength_set"attaches the Ring of Weakness curse when its onset ends. Pass anallocatorto the ledger'sadvancefor it.
An effect on a location has no bearer, so its outcome never runs.
condition
class-attribute
instance-attribute
condition: Condition | None = None
A Condition granted when the effect attaches and taken back when it
expires or is released. When the target is immune to the condition, nothing attaches, and the attach
returns no effect.
modifiers
class-attribute
instance-attribute
modifiers: tuple[ModifierSpec, ...] = ()
The ModifierSpec adjustments granted while the effect lasts and
taken back when it ends.
dispellable
class-attribute
instance-attribute
dispellable: bool = False
True marks the effect as one dispel magic can end. Everything
cast_spell attaches is dispellable, permanent effects included. What a
monster inflicts isn't.
params
class-attribute
instance-attribute
Any other values the effect's tick, its expiry outcome, or other code that reads the effect needs. The keys osrlib reads include these:
- For the
"regeneration"tick:per_round,delay_rounds,revive, andwhile_alive, asregeneration_definitiondescribes them. - For the
"splash_damage"outcome:dice, the damage roll,element, andkeys, the damage keys. - For the
"weakness_strength_set"outcome:strength_set, the strength score the curse sets. - For
natural_healing:healing_rest_days, the number of rest days for each natural heal.
osrlib ignores any key it doesn't read, so you can store your own values here.
EffectsLedger
Bases: BaseModel
The object that contains every running effect and resolves each one as the game clock moves.
One ledger covers a whole game. A GameSession creates one and keeps it
as session.ledger for the life of the session. When you run the rules without a session, construct one with
EffectsLedger() and keep it beside your GameClock. It's a pydantic model,
so you save it with model_dump and restore it with model_validate, along with the clock and the creatures.
Its methods:
attachputs an effect on a target.advancemoves the clock and resolves every expiry and tick in the time that passes.releaseends an effect early.active_onlists the effects on one target.
Only advance ends an effect when its time runs out. If you move the clock any other way, effects that should
have expired stay in place, so always move the clock through the ledger.
Examples:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EFFECTS_STREAM, Condition, EffectDefinition, EffectsLedger, has_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=3)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
ledger = EffectsLedger()
clock = GameClock()
web = EffectDefinition(
kind="web",
duration_unit=TimeUnit.TURN,
duration_amount=2,
condition=Condition.ENTANGLED,
)
effect, _ = ledger.attach(web, "monster-0001", clock=clock, allocator=IdAllocator(), registry=registry)
assert effect is not None and effect.expires_round == 120 # two turns of sixty rounds
# One turn on, the web still holds.
ledger.advance(clock, 1, TimeUnit.TURN, registry, stream=streams.get(EFFECTS_STREAM))
assert has_condition(goblin, Condition.ENTANGLED)
# One more, and it lets go.
ledger.advance(clock, 1, TimeUnit.TURN, registry, stream=streams.get(EFFECTS_STREAM))
assert not has_condition(goblin, Condition.ENTANGLED)
effects
class-attribute
instance-attribute
effects: list[ActiveEffect] = []
Every running ActiveEffect, in the order they were attached. Read it
to see everything running at once. To find the effects on one target, call
active_on. attach, release, and advance update the
list.
active_on
active_on(target_ref: str, kind: str | None = None) -> list[ActiveEffect]
Return the effects currently running on one target.
Use this for questions that has_condition and the modifier
functions can't answer, like whether a mirror image is still up or how many rounds a light source has
left. Pass kind to get only the effects of that kind. The list is empty when none match.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_ref
|
str
|
The entity id or location string the effects are attached to. |
required |
kind
|
str | None
|
An |
None
|
Returns:
| Type | Description |
|---|---|
list[ActiveEffect]
|
The matching effects, in the order they were attached. The list is new, but the effects in it are the ledger's objects, so a change to one changes what the ledger runs. |
Examples:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import Condition, EffectDefinition, EffectsLedger
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
spawn = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
ledger, clock = EffectsLedger(), GameClock()
sleep = EffectDefinition(
kind="sleep",
duration_unit=TimeUnit.TURN,
duration_amount=4,
condition=Condition.ASLEEP,
)
ledger.attach(sleep, "monster-0001", clock=clock, allocator=IdAllocator(), registry=registry)
for effect in ledger.active_on("monster-0001", "sleep"):
print(effect.effect_id, effect.expires_round - clock.rounds)
# effect-0001 240
attach
attach(
definition: EffectDefinition,
target_ref: str,
*,
clock: GameClock,
allocator: Any,
registry: Mapping[str, Any] | None = None,
stream: RngStream | None = None,
caster_level: int | None = None
) -> tuple[ActiveEffect | None, list[Event]]
Put an effect on a target and return it with the events the attach produced.
Every effect starts here. Build an EffectDefinition and call
this with the target's entity id. The ledger works out when the effect expires, grants the condition and
modifiers it brings, and starts counting its ticks. Afterwards, move the clock with
advance, which expires and ticks the effect.
When a spell attaches the effect, cast_spell makes this call for you
and returns the same events.
The call can return None instead of an effect, so check before you use it. That happens in two cases.
The definition's stacking is "ignore" and the target already has an effect of that kind, or the
target's template lists the definition's condition in its condition_immunities. When stacking is
"refresh" and the target already has an effect of that kind, you get the existing effect back with its
duration restarted, and no events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
definition
|
EffectDefinition
|
The blueprint to attach. |
required |
target_ref
|
str
|
The entity id of the creature, or the location string of the place, to attach to. For an
id that isn't a key in |
required |
clock
|
GameClock
|
The game clock. The duration and the tick count start from its current round. The call reads the clock and doesn't advance it. |
required |
allocator
|
Any
|
The |
required |
registry
|
Mapping[str, Any] | None
|
The creatures in play by entity id, so the attach can grant conditions and modifiers. Pass None, or leave the target out of it, and the effect attaches without granting anything. |
None
|
stream
|
RngStream | None
|
The effects stream, |
None
|
caster_level
|
int | None
|
The level of the caster, recorded on the effect for dispel magic to roll against. Leave it None for an effect that doesn't come from a caster. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[ActiveEffect | None, list[Event]]
|
A pair of the attached effect and its events. The events are the
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the definition has |
Examples:
A sleep takes hold on a goblin, and a skeleton, which is immune to sleep, gets None:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import Condition, EffectDefinition, EffectsLedger
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
spawn = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
monsters = load_monsters()
goblin = spawn_monster(monsters.get("goblin"), id="monster-0001", stream=spawn)
skeleton = spawn_monster(monsters.get("skeleton"), id="monster-0002", stream=spawn)
registry = {"monster-0001": goblin, "monster-0002": skeleton}
ledger, clock, allocator = EffectsLedger(), GameClock(), IdAllocator()
sleep = EffectDefinition(
kind="sleep",
duration_unit=TimeUnit.TURN,
duration_amount=4,
condition=Condition.ASLEEP,
)
effect, events = ledger.attach(sleep, "monster-0001", clock=clock, allocator=allocator, registry=registry)
print(effect.effect_id, effect.expires_round, [event.code for event in events])
# effect-0001 240 ['effects.effect.attached', 'effects.condition.gained']
print(ledger.attach(sleep, "monster-0002", clock=clock, allocator=allocator, registry=registry))
# (None, [])
release
End an effect before its duration runs out.
Call this when something in the game cuts an effect short, like a dispel magic, a light source put out, or an invisible creature that attacks and loses its invisibility. The condition and the modifiers the effect granted come off with it.
Find the id first with active_on. It returns a new list,
so you can release each effect in it as you loop. Don't loop over effects itself while you release,
because each release removes an entry from that list. You don't call this when time runs out:
advance expires the effect and emits an
EffectExpiredEvent instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
effect_id
|
str
|
The |
required |
registry
|
Mapping[str, Any] | None
|
The creatures in play by entity id, so the ledger can take back the condition and modifiers. You can leave it out only for an effect whose definition grants neither. |
None
|
Returns:
| Type | Description |
|---|---|
list[Event]
|
The |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the ledger has no effect with that id, usually because it already expired or was
released, or if the effect's definition grants a condition or modifiers and you passed no
|
Examples:
A dispel that ends every effect on a goblin:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import Condition, EffectDefinition, EffectsLedger, has_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
spawn = RngStreams(master_seed=3).get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
ledger = EffectsLedger()
sleep = EffectDefinition(
kind="sleep",
duration_unit=TimeUnit.TURN,
duration_amount=4,
condition=Condition.ASLEEP,
)
ledger.attach(sleep, "monster-0001", clock=GameClock(), allocator=IdAllocator(), registry=registry)
for effect in ledger.active_on("monster-0001"):
print([event.code for event in ledger.release(effect.effect_id, registry)])
# ['effects.effect.released', 'effects.condition.removed']
print(has_condition(goblin, Condition.ASLEEP), ledger.effects)
# False []
advance
advance(
clock: GameClock,
n: int,
unit: TimeUnit,
registry: Mapping[str, Any],
*,
stream: RngStream,
allocator: Any | None = None
) -> list[Event]
Move the game clock forward and resolve everything the passing time triggers.
This call ends effects whose duration runs out and runs periodic ticks, like a troll's regeneration.
Move the clock with this call rather than with GameClock.advance
or by setting GameClock.rounds. The clock records only the time, so
moving it directly resolves no effects. A GameSession makes this call
for you in advance_rounds and
advance_turns.
The call resolves every round in the span, one at a time, in the same order. First, it suspends the effects on a creature that another effect has petrified. A suspended effect neither ticks nor ages: its expiry moves forward one round for each round it is suspended. Then expirations resolve, and then ticks. Within each phase, effects go in attachment order, and effect id breaks a tie. The same span therefore always produces the same events in the same order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
clock
|
GameClock
|
The game clock. The call advances it in place, so it shows the new time when the call returns. |
required |
n
|
int
|
How many units to advance. The call resolves every round in the span, so a long span costs more: a day is thousands of rounds. |
required |
unit
|
TimeUnit
|
The unit |
required |
registry
|
Mapping[str, Any]
|
The creatures in play by entity id, so the call can write conditions, modifiers, and hit points. A plain dict works. |
required |
stream
|
RngStream
|
The effects stream, |
required |
allocator
|
Any | None
|
The |
None
|
Returns:
| Type | Description |
|---|---|
list[Event]
|
Every event the span produced, in the order it was produced. Add them to your event log. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
A troll that took ten points of damage regenerates three of them a round:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EFFECTS_STREAM, EffectsLedger, regeneration_definition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=9)
template = load_monsters().get("troll")
troll = spawn_monster(template, id="monster-0001", stream=streams.get(MONSTER_SPAWN_STREAM))
registry = {"monster-0001": troll}
troll.current_hp -= 10
ledger = EffectsLedger()
clock = GameClock()
definition = regeneration_definition(template.ability("regeneration").params)
ledger.attach(definition, "monster-0001", clock=clock, allocator=IdAllocator(), registry=registry)
events = ledger.advance(clock, 2, TimeUnit.ROUND, registry, stream=streams.get(EFFECTS_STREAM))
assert [event.code for event in events] == [
"effects.effect.ticked",
"combat.healing.applied",
"combat.state.hit_points",
"effects.effect.ticked",
"combat.healing.applied",
"combat.state.hit_points",
]
assert troll.current_hp == troll.max_hp - 4 # six of the ten points back
ModifierSpec
Bases: BaseModel
One adjustment to a combat statistic, granted by an effect or by an equipped magic item.
You write these when you author a spell, a magic item, or an effect of your own. Put them in an
EffectDefinition's modifiers. Attaching that definition turns
each spec into an ActiveModifier in the creature's stat_modifiers,
and the combat functions read them back through modifier_total and the
other modifier functions. A magic item template lists specs too. The combat functions read an equipped item's
specs through
equipped_item_modifiers instead, and they never appear in
stat_modifiers. A spec is frozen, so the same one can be in several definitions.
The scope fields, element, versus_other_alignment, save_categories, and melee_only, narrow when the
modifier counts. Leave them at their defaults and the modifier applies to every roll of its kind.
Examples:
from osrlib.core.effects import ModifierSpec
bless = ModifierSpec(kind="attack_bonus", value=1)
resist_fire = ModifierSpec(kind="save_bonus", value=2, element="fire")
assert bless.dice is None and not bless.from_item
assert resist_fire.element == "fire"
kind
instance-attribute
kind: str
Which statistic the modifier adjusts, one of MODIFIER_KINDS. Any
other value raises pydantic's ValidationError.
value
class-attribute
instance-attribute
value: int = 0
The signed adjustment, like +1 for bless's attack bonus or -1 for protection from evil's penalty on
attackers. For ac_set and ac_set_vs_missile it's the armour class to set, and for strength_set the
strength score. Leave it at 0 for a kind that uses dice or acts as a flag.
dice
class-attribute
instance-attribute
dice: str | None = None
A dice expression rolled instead of adding value, for a kind that grants dice, like striking's "1d6"
of extra weapon damage. osrlib checks it with parse, so a malformed
expression raises ContentValidationError when you build the
ModifierSpec, not when the combat code rolls it.
element
class-attribute
instance-attribute
element: str | None = None
Narrows the modifier to one damage or save element, like "fire" for resist fire. The modifier counts
only for a roll with that same element. None means every element.
versus_other_alignment
class-attribute
instance-attribute
versus_other_alignment: bool = False
True narrows the modifier to rolls against creatures of a different alignment, which is how protection
from evil works. The modifier then counts only when the call that reads it passes versus_differs=True.
save_categories
class-attribute
instance-attribute
Narrows a save bonus to the named saving throw categories. A Displacer Cloak, for example, covers
"paralysis", "wands", and "spells" but not the others. Empty means every category.
melee_only
class-attribute
instance-attribute
melee_only: bool = False
True narrows the modifier to melee attacks. That's how the Displacer Cloak's -2 on attackers leaves
missile attacks alone. The modifier then counts only when the call that reads it passes melee=True.
from_item
class-attribute
instance-attribute
from_item: bool = False
True marks the modifier as coming from a magic item rather than a spell. Such a modifier is exempt from
the rule that only the largest spell bonus and the largest spell penalty count:
modifier_total adds every item modifier to the capped spell total.
Set it on the effects of potions and scrolls as well as worn items, because the rule covers magic items in
general.
grant_condition
Put a condition on a creature and return the event that reports it.
Call this for a state that doesn't come from a timed effect, the way kill does
for dead. When the state has a duration, set the condition on an
EffectDefinition and attach it with
EffectsLedger.attach instead. The ledger then takes the
condition back when the duration runs out. A condition granted here stays until you call
remove_condition with the same effect_id.
The call replaces the creature's conditions tuple on the object you pass, so pass the creature that is in
play, not a copy. Add the returned events to your event log.
In two cases, the call grants nothing and returns no events. A monster whose template lists the condition in its
defenses' condition_immunities is never affected, which is why a skeleton can't be put to sleep. A second
grant of the same condition with the same effect_id changes nothing, because the creature already has that
record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
condition
|
Condition
|
The condition to grant. |
required |
effect_id
|
str | None
|
The id of the effect that grants the condition and will take it back, or |
required |
Returns:
| Type | Description |
|---|---|
list[Event]
|
A list of one |
Examples:
from osrlib.core.effects import Condition, grant_condition, has_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
events = grant_condition(goblin, Condition.AFRAID, "effect-0001")
assert [event.code for event in events] == ["effects.condition.gained"]
assert has_condition(goblin, Condition.AFRAID)
# The same grant a second time changes nothing and says nothing.
assert grant_condition(goblin, Condition.AFRAID, "effect-0001") == []
has_condition
Return whether a creature currently has a condition.
The combat functions make the same call. Use it wherever your code asks "is this creature asleep" instead of
scanning the creature's conditions tuple, which can contain the same condition more than once, from different
effects.
It doesn't report which effect granted the condition. When you need that, read the creature's conditions
tuple of ActiveCondition records directly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
condition
|
Condition
|
The condition to look for. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when the creature has that condition from any source. |
Examples:
from osrlib.core.effects import Condition, grant_condition, has_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
assert not has_condition(goblin, Condition.AFRAID)
grant_condition(goblin, Condition.AFRAID, "effect-0001")
assert has_condition(goblin, Condition.AFRAID)
has_modifier
Return whether a creature has any modifier of one kind.
Use this for the kinds that act as flags rather than numbers, where having the modifier at all is the
rule: counts_as_magical, missile_immunity_nonmagical, and magical_healing_half. For a kind that uses
a number, call modifier_total. A total of 0 from it can mean either
that the creature has no modifier of the kind or that its modifiers cancel out.
It ignores the scope fields, so a modifier narrowed to one element still counts here. When you need the
scope fields applied, call modifier_values. It reads only the
creature's stat_modifiers, not an equipped magic item's modifiers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
kind
|
str
|
The statistic to look for, one of |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when the creature has at least one modifier of that kind. |
Examples:
from osrlib.core.clock import GameClock
from osrlib.core.effects import EffectDefinition, EffectsLedger, ModifierSpec, has_modifier
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
enchanted = EffectDefinition(
kind="striking",
modifiers=(ModifierSpec(kind="counts_as_magical", value=1),),
)
ledger = EffectsLedger()
ledger.attach(enchanted, "monster-0001", clock=GameClock(), allocator=IdAllocator(), registry=registry)
assert has_modifier(goblin, "counts_as_magical")
assert not has_modifier(goblin, "missile_immunity_nonmagical")
kill
Kill a creature outright: hit points to zero, the dead condition, and the death events.
In B/X a creature dies the moment it drops to zero hit points or fewer.
deal_damage calls this for you when damage does that. Call it yourself
for a death that doesn't come from damage, like a failed save against finger of death, or a creature you
remove from play by decision.
The dead condition granted here has no effect_id, because no effect grants it. Calling kill on a creature
that is already dead returns no events and changes nothing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
permanent
|
bool
|
True when a regenerating creature can't come back, which for a troll means its
non-regenerable damage has reached its maximum hit points. It changes the death event's code from
|
False
|
Returns:
| Type | Description |
|---|---|
list[Event]
|
The |
Examples:
from osrlib.core.effects import Condition, has_condition, kill
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
events = kill(goblin)
assert [event.code for event in events] == [
"effects.condition.gained",
"combat.death.died",
"combat.state.hit_points",
]
assert goblin.current_hp == 0
assert has_condition(goblin, Condition.DEAD)
assert kill(goblin) == [] # already dead
modifier_dice
Return the dice expression of a creature's dice-valued modifier of one kind.
A few modifiers grant dice instead of a flat number, like striking's extra "1d6" of weapon damage.
Call this to find them, then roll the expression yourself with roll. For a flat
adjustment, call modifier_total instead.
It returns only the first matching modifier, in the order the effects were attached. That's the rule that
spells don't add up, applied to dice: a creature under two strikings rolls one extra die, not two. It
ignores the scope fields and modifiers that have no dice, and it reads only the creature's stat_modifiers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
kind
|
str
|
The statistic to look for, one of |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The dice expression, in the notation |
Examples:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EffectDefinition, EffectsLedger, ModifierSpec, modifier_dice
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
striking = EffectDefinition(
kind="striking",
duration_unit=TimeUnit.TURN,
duration_amount=6,
modifiers=(ModifierSpec(kind="weapon_damage_dice_bonus", dice="1d6"),),
)
ledger = EffectsLedger()
ledger.attach(striking, "monster-0001", clock=GameClock(), allocator=IdAllocator(), registry=registry)
assert modifier_dice(goblin, "weapon_damage_dice_bonus") == "1d6"
assert modifier_dice(goblin, "damage_bonus") is None
modifier_total
modifier_total(
target: Creature,
kind: str,
*,
element: str | None = None,
versus_differs: bool = False,
save_category: str | None = None,
melee: bool = False
) -> int
Return the one number to add to a roll for a creature's modifiers of one kind.
The combat functions make this call, and it's the one to use when you resolve a roll of your own. It reads the same
modifiers that modifier_values returns and combines them into one
signed adjustment. Spells that affect the same statistic don't add up: only the largest bonus and the largest
penalty count. Two blesses give +1, not +2, while a bless and a blight cancel out.
The function adds every modifier marked from_item on top, outside that rule, because the rule covers spells and
not magic items. The scope arguments work as they do for modifier_values.
It reads only the creature's stat_modifiers, which come from attached effects. An
equipped magic item's modifiers aren't there: get those from
equipped_item_modifiers and add them yourself.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
kind
|
str
|
The statistic to total, one of |
required |
element
|
str | None
|
The damage or save element of the roll, like |
None
|
versus_differs
|
bool
|
True when the other creature in the roll has a different alignment from the target. |
False
|
save_category
|
str | None
|
The saving throw category of the roll, a
|
None
|
melee
|
bool
|
True when the roll is for a melee attack. |
False
|
Returns:
| Type | Description |
|---|---|
int
|
The signed adjustment to add to the roll, or 0 when nothing applies. |
Examples:
Two blessings and one blight on the same goblin count one point of bonus and one point of penalty, which cancel out:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EffectDefinition, EffectsLedger, ModifierSpec, modifier_total, modifier_values
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
ledger, clock, allocator = EffectsLedger(), GameClock(), IdAllocator()
bless = EffectDefinition(
kind="bless",
duration_unit=TimeUnit.TURN,
duration_amount=6,
modifiers=(ModifierSpec(kind="attack_bonus", value=1),),
)
blight = EffectDefinition(
kind="blight",
duration_unit=TimeUnit.TURN,
duration_amount=6,
modifiers=(ModifierSpec(kind="attack_bonus", value=-1),),
)
for definition in (bless, bless, blight):
ledger.attach(definition, "monster-0001", clock=clock, allocator=allocator, registry=registry)
assert modifier_values(goblin, "attack_bonus") == [1, 1, -1]
assert modifier_total(goblin, "attack_bonus") == 0
modifier_values
modifier_values(
target: Creature,
kind: str,
*,
element: str | None = None,
versus_differs: bool = False,
save_category: str | None = None,
melee: bool = False
) -> list[int]
Return every modifier value of one kind that applies to the situation you describe.
Use this when you need the separate values rather than one number. The armour class code, for example, reads
the ac_set values one at a time and uses the best. When you want one number to add to a roll, call
modifier_total instead, which also applies the rule that spell bonuses
don't add up.
The keyword arguments describe the roll, and the function leaves out a modifier narrowed to something you
don't pass.
A modifier with an element counts only when you pass that element. One with versus_other_alignment
counts only when you pass versus_differs=True. A save bonus with save_categories counts only when you pass
one of its categories, and a melee_only modifier only when you pass melee=True.
It reads only the creature's stat_modifiers, which come from attached effects. An
equipped magic item's modifiers aren't there: get those from
equipped_item_modifiers and add them yourself.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
kind
|
str
|
The statistic to look for, one of |
required |
element
|
str | None
|
The damage or save element of the roll, like |
None
|
versus_differs
|
bool
|
True when the other creature in the roll has a different alignment from the target. |
False
|
save_category
|
str | None
|
The saving throw category of the roll, a
|
None
|
melee
|
bool
|
True when the roll is for a melee attack. |
False
|
Returns:
| Type | Description |
|---|---|
list[int]
|
The signed values of the modifiers that apply, in the order their effects were attached. Empty when none apply. |
Examples:
from osrlib.core.clock import GameClock, TimeUnit
from osrlib.core.effects import EffectDefinition, EffectsLedger, ModifierSpec, modifier_values
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
registry = {"monster-0001": goblin}
resist_fire = EffectDefinition(
kind="resist_fire",
duration_unit=TimeUnit.TURN,
duration_amount=12,
modifiers=(ModifierSpec(kind="save_bonus", value=2, element="fire"),),
)
ledger = EffectsLedger()
ledger.attach(resist_fire, "monster-0001", clock=GameClock(), allocator=IdAllocator(), registry=registry)
assert modifier_values(goblin, "save_bonus", element="fire") == [2]
assert modifier_values(goblin, "save_bonus", element="cold") == []
regeneration_definition
regeneration_definition(params: Mapping[str, Any]) -> EffectDefinition
Build the effect definition for a monster that regenerates.
A regenerating monster like a troll has a regeneration ability. Its params set how fast the monster heals
and whether it comes back from death. Get them with template.ability("regeneration").params, pass them here,
and attach the result to the monster with EffectsLedger.attach
when it enters play. From then on, advance heals the monster in
each round it resolves, while the monster is hurt.
The definition has no duration, so the regeneration runs until you release it. Its stacking is
"ignore", so a second attach to the same monster changes nothing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Mapping[str, Any]
|
The ability's params. The tick reads these keys. |
required |
Returns:
| Type | Description |
|---|---|
EffectDefinition
|
An |
Raises:
| Type | Description |
|---|---|
ContentValidationError
|
If |
Examples:
from osrlib.core.effects import regeneration_definition
from osrlib.data import load_monsters
ability = next(a for a in load_monsters().get("troll").abilities if a.tag == "regeneration")
definition = regeneration_definition(ability.params)
assert definition.kind == "regeneration" and definition.tick == "regeneration"
assert definition.duration_unit is None # it runs until released
assert definition.params["per_round"] == 3
remove_condition
Take back the condition one effect granted, and return the event that reports it.
This undoes grant_condition. It removes only the record that matches
both the condition and the effect_id, so pass the effect_id you granted the condition with, or the call
removes nothing. A creature charmed by two effects keeps the second charm after you remove the first.
Call this for conditions you granted yourself. A condition from an attached effect comes off when the effect
expires, or when you end the effect with EffectsLedger.release.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Creature
|
The |
required |
condition
|
Condition
|
The condition to take back. |
required |
effect_id
|
str | None
|
The |
required |
Returns:
| Type | Description |
|---|---|
list[Event]
|
A list of one |
Examples:
from osrlib.core.effects import Condition, grant_condition, has_condition, remove_condition
from osrlib.core.monsters import MONSTER_SPAWN_STREAM, spawn_monster
from osrlib.core.rng import RngStreams
from osrlib.data import load_monsters
streams = RngStreams(master_seed=5)
spawn = streams.get(MONSTER_SPAWN_STREAM)
goblin = spawn_monster(load_monsters().get("goblin"), id="monster-0001", stream=spawn)
grant_condition(goblin, Condition.AFRAID, "effect-0001")
# A different owner removes nothing.
assert remove_condition(goblin, Condition.AFRAID, "effect-0002") == []
assert has_condition(goblin, Condition.AFRAID)
events = remove_condition(goblin, Condition.AFRAID, "effect-0001")
assert [event.code for event in events] == ["effects.condition.removed"]
assert not has_condition(goblin, Condition.AFRAID)