Skip to content

osrlib.core.ruleset

The house rules for a game, as one frozen set of flags.

Ruleset is the entry point and almost the whole module. Build one at the start of a game, pass it to GameSession.new or, away from a session, to each kernel function that takes a ruleset argument. The model is frozen, so a game uses one ruleset from start to finish. The rules functions read its flags on every call, so there's no setup step. A save contains the ruleset, so a loaded game uses the rules it began with.

Ruleset() with no arguments gives you the SRD rules as written. Each flag is either an optional rule or an adaptation. An optional rule is an alternative the SRD prints beside its default procedure. An adaptation is a default osrlib chooses for a decision that the tabletop game leaves to a human referee. A program that runs without a referee has to make that decision. The two enum flags, EncumbranceMode and XpAwardTiming, pick among alternatives instead of switching one behavior on and off.

Each flag is a field of Ruleset, documented there and in the ruleset options guide with what each flag changes in play. The adaptations register lists each default osrlib supplies for a decision the tabletop game leaves to a referee, with the reasoning behind each one.

Typical usage:

from osrlib.core.ruleset import EncumbranceMode, Ruleset, XpAwardTiming

# The SRD as written.
rules = Ruleset()
assert rules.variable_weapon_damage is True
assert rules.encumbrance is EncumbranceMode.BASIC
assert rules.xp_award_timing is XpAwardTiming.ON_RETURN

# A game that pays experience out as it's earned and tracks no encumbrance.
house_rules = Ruleset(xp_award_timing=XpAwardTiming.IMMEDIATE, encumbrance=EncumbranceMode.NONE)
assert house_rules.variable_weapon_damage is True

EncumbranceMode

Bases: StrEnum

Which system osrlib uses to track what the party carries, and how much it slows them down.

Set it on Ruleset.encumbrance. The weights and the movement rates are in osrlib.core.items, and movement_rate_feet reads this choice.

Saved games contain the lowercase values, and they stay fixed within a schema_version, the version stamp that identifies a serialized model's format.

NONE class-attribute instance-attribute

NONE = 'none'

Track nothing: every character moves at the base rate of 120 feet per turn, whatever they carry.

BASIC class-attribute instance-attribute

BASIC = 'basic'

Set movement rate from worn armour, and from whether the character carries a significant amount of treasure.

This is the SRD's default and the mode Ruleset() uses. A character whose tracked weight passes the maximum load can't move at all.

DETAILED class-attribute instance-attribute

DETAILED = 'detailed'

Total the coin weight of armour, gear, and treasure, and set movement rate from banded weight thresholds.

It counts more than BASIC does. The maximum load is the same, and past it the character can't move.

Ruleset

Bases: BaseModel

The rules for a game: one flag per decision osrlib lets you make.

Build one at the start of a game and pass it to GameSession.new, or to each kernel function that takes a ruleset argument. Ruleset() gives you the SRD rules as written, so pass only the flags you want to change. The model is frozen, so you can't change a ruleset mid-game. Saves and replays contain it, so a resumed game uses the rules it started with. An unknown field name raises a pydantic ValidationError, so a misspelled flag fails instead of doing nothing.

Each flag is one of two kinds. An optional rule is an alternative the SRD prints beside its standard procedure, and osrlib's default is the book's. An adaptation is a default osrlib supplies where the tabletop game leaves the decision to a human referee. The adaptations register gives the reasoning behind each one.

Examples:

from osrlib.core.ruleset import Ruleset

rules = Ruleset(individual_initiative=True, hp_reroll_at_first_level=True)
assert rules.individual_initiative is True

# The rest keep the book's defaults.
assert rules.thac0_arithmetic is False
assert rules.magic_item_death_save is True

hp_reroll_at_first_level class-attribute instance-attribute

hp_reroll_at_first_level: bool = False

Reroll a first-level hit die that comes up 1 or 2. An optional rule, off by default.

Turn it on and osrlib rerolls the raw die until it shows 3 or more, before the CON modifier is added, so a first-level character starts with at least 3 hit points before that modifier.

encumbrance class-attribute instance-attribute

Which system tracks carried weight and sets movement rate. Basic by default.

See EncumbranceMode for what each mode counts, and osrlib.core.items for the weights and rates it reads.

variable_weapon_damage class-attribute instance-attribute

variable_weapon_damage: bool = True

Let each weapon deal the damage its description lists. An optional rule, on by default.

Turn it off and every weapon deals 1d6, and so does every piece of gear swung as one, which is the SRD's baseline combat system. The exception is a character wearing a girdle of giant strength, whose weapon attacks deal 2d8. With the flag on, the girdle doubles weapon damage instead. Either way, an unarmed attack deals 1d2, and monsters deal the damage printed in their descriptions.

individual_initiative class-attribute instance-attribute

individual_initiative: bool = False

Roll initiative for each combatant instead of once per side. An optional rule, off by default.

Turn it on and every participant rolls a separate 1d6. A character adds its DEX modifier, and a halfling also adds its class initiative bonus. The tabletop game leaves a monster's initiative modifier to the referee, so you pass one to participant_modifier, and it's 0 if you don't.

thac0_arithmetic class-attribute instance-attribute

thac0_arithmetic: bool = False

Work out the attack target number by subtraction instead of reading the attack matrix.

An optional rule, off by default. Turn it on and the number to roll is THAC0 − AC with no clamping. The SRD's ascending-armour-class procedure is the same arithmetic, so this one flag covers both. Every number in the matrix is within 2 to 20, and the subtraction has no such limit, so the two differ only when THAC0 − AC falls outside that range.

weapon_reload class-attribute instance-attribute

weapon_reload: bool = False

Stop a weapon with the reload quality, mainly the crossbow, from firing two rounds running.

An optional rule, off by default. Turn it on and the attack validator refuses the shot when the combat context you pass shows the weapon fired last round. In a session, the battle code records what fired each round. Without a session, you set that in the context yourself.

hd5_counts_as_magical class-attribute instance-attribute

hd5_counts_as_magical: bool = False

Let big monsters hurt creatures that only silver or magic weapons can harm. An optional rule, off by default.

The SRD prints this among its invulnerability rules. Turn it on, and a monster with 5 or more Hit Dice gets past such a defense. So does a monster that has the same kind of defense itself. A monster that energy drain has taken Hit Dice from counts only the Hit Dice it has left. osrlib applies the rule only where the defense is limited to silver and magic, as the rule is worded. It reads "another invulnerable monster" as a monster with such a defense.

magic_item_death_save class-attribute instance-attribute

magic_item_death_save: bool = True

Give a dead character's magic items a saving throw against the effect that killed their owner.

An optional rule the SRD leaves to the referee, on by default. It applies when a destructive source, like a breath weapon or disintegrate, kills a character and destroys their equipment. osrlib rolls a save for each magic item in the dead character's inventory, using the owner's save values against the source's category and adding the item's best combat bonus. An item that saves isn't destroyed. Turn the flag off and every item is destroyed.

xp_award_timing class-attribute instance-attribute

When the party receives earned experience. On return by default, which is the tabletop rule.

See XpAwardTiming. The immediate setting is an adaptation, and it suits a game whose party never goes home.

deprivation_penalties class-attribute instance-attribute

deprivation_penalties: bool = False

Attach mechanical penalties to going without food or water. An adaptation, off by default.

The tabletop rules leave starvation penalties to the referee. osrlib tracks the party's food and water either way, so this flag changes only what happens once they run out. Turn it on and osrlib applies this schedule, which it bases on the SRD's examples:

  • After one full day without food or water, −1 to attack rolls, and the character needs rest twice as often, so fatigue sets in after three turns without rest instead of six.
  • After two days, movement rate also halves.
  • From the third day on, the character also loses 1d4 hit points each day.

Hunger and thirst don't add together: the longer of the two counts. The adaptations register has the reasoning.

aoe_friendly_fire class-attribute instance-attribute

aoe_friendly_fire: bool = True

Let an area effect cast at a monster group in melee catch the party members fighting it.

An adaptation, on by default. Turn it off and an area effect aimed at a monster group never counts party members among its targets, so a fireball is safe to cast at monsters the party is fighting in melee.

formation_width_limit class-attribute instance-attribute

formation_width_limit: bool = True

Cap how many combatants can fight side by side, by how wide the passage is.

An adaptation, on by default. The cap is the party's frontage, the width of the space it fights across, divided by the five feet one combatant needs. Each dungeon cell is ten feet wide, so two may fight side by side in a one-cell corridor and four in a room two cells across. The SRD notes that two or three characters can fight side by side in a ten-foot passage, and osrlib uses the lower number. Turn the flag off and there's no cap, so every combatant may melee.

failed_trap_removal_springs class-attribute instance-attribute

failed_trap_removal_springs: bool = True

Spring a treasure trap on the thief who fails to remove it. An adaptation, on by default.

The SRD says a thief may try only once to remove a treasure trap, and it doesn't say what a failure does. Turn the flag off and a failed RemoveTreasureTrap leaves the trap armed. The party still knows where it is. That thief can't try again, another thief in the party can, and the trap still gets its 2-in-6 chance to spring when someone takes the treasure.

XpAwardTiming

Bases: StrEnum

When a party receives the experience points it has earned.

Set it on Ruleset.xp_award_timing. The choice affects the game's pacing. With ON_RETURN, the party gets its experience only once it's back in town alive. With IMMEDIATE, it gets experience as it earns it, which suits a game with no trip home.

Saved games contain the lowercase values, and they stay fixed within a schema_version, the version stamp that identifies a serialized model's format.

ON_RETURN class-attribute instance-attribute

ON_RETURN = 'on_return'

Award experience when the party survives and returns to town, as in the tabletop rules.

osrlib awards the experience for defeated monsters and recovered treasure only when the party gets back to town. Treasure lost on the way earns nothing.

IMMEDIATE class-attribute instance-attribute

IMMEDIATE = 'immediate'

Award experience as it's earned: monsters at the end of each encounter, treasure as it's picked up.

This is an adaptation for continuous play, where the party may never make a trip home. The party gets nothing extra when it reaches town, and dropping treasure doesn't take the experience back.