Skip to content

osrlib.core.abilities

What a character's six ability scores are worth, and what you can do with them.

Start with load_ability_tables, which gives you an AbilityTables with the SRD's printed tables. Pass any of its accessors a score from 3 to 18 and get the number that applies: the melee modifier for strength, the armour class modifier for dexterity, the hit points per Hit Die for constitution, and so on. A Character has properties for these results, so call the accessors yourself only when you have a bare score and no character.

The module also has two functions that roll dice. ability_check rolls the SRD's general check for a task the rules don't otherwise cover, and open_doors_check rolls a strength-based attempt to force a stuck door. Both take an RngStream.

The rest of the module is the third step of character creation, where a player trades points between abilities before play. validate_adjustment reports whether a proposed trade is legal, and apply_adjustment applies it. create_character runs the whole creation sequence, so call these two only when you build a character step by step and let a player choose.

The members, in the order you use them:

Scores run 3 to 18. That's the range of a 3d6 roll and of the SRD's tables, and the adjustment step can't take a score outside it.

Typical usage:

from osrlib.core.abilities import ability_check
from osrlib.core.rng import RngStreams
from osrlib.data import load_ability_tables

tables = load_ability_tables()

# What a strength of 16 is worth.
assert tables.melee_modifier(16) == 2
assert tables.open_doors_chance(16) == 4

# A check against a dexterity of 13, on a stream you supply.
check = ability_check(13, RngStreams(master_seed=3).get("exploration"))
assert (check.roll, check.success) == (18, False)

ADJUSTMENT_FLOOR module-attribute

ADJUSTMENT_FLOOR = 9

The lowest a score may be traded down to during character creation, which is 9.

The floor stops a player from emptying one ability to buy up another. It applies only to the trade in validate_adjustment. A score rolled below 9 is legal, and the trade can't lower it further.

MAX_SCORE module-attribute

MAX_SCORE = 18

The highest an ability score can be, which is 18.

Eighteen is what three dice showing 6 add up to, and the top row of every table here. When a player trades points at character creation, the trade can't raise a score past it. The accessors and ability_check raise ValueError above it, because the tables have no row for a higher score.

MIN_SCORE module-attribute

MIN_SCORE = 3

The lowest an ability score can be, which is 3.

Three is what three dice showing 1 add up to, and the lowest row of every table here. Below it there's no rule to apply, so the accessors and ability_check raise ValueError instead of guessing. Use it to bound a slider, or to check a score your own code produced.

AbilityAdjustment

Bases: BaseModel

A proposed trade of ability points, made once while a character is being created.

Build one from what the player chose, check it with validate_adjustment, and apply it with apply_adjustment, or pass it to create_character as adjustment. The exchange rate is two points down for one point up. The points bought can go only into the class's prime requisites, the abilities the class is built around. An amount of zero or less raises a pydantic ValidationError.

An empty adjustment is legal and changes nothing. Build one for a player who keeps the scores as rolled.

Examples:

from osrlib.core.abilities import AbilityAdjustment, AbilityScore

# Four points out of intelligence and wisdom buys two points of strength.
adjustment = AbilityAdjustment(
    lowered={AbilityScore.INT: 2, AbilityScore.WIS: 2},
    raised={AbilityScore.STR: 2},
)
assert sum(adjustment.raised.values()) == sum(adjustment.lowered.values()) // 2

lowered class-attribute instance-attribute

lowered: dict[AbilityScore, int] = {}

How much to take off each ability, as a positive number.

Only strength, intelligence, and wisdom may appear, each amount must be even, and no score may end below ADJUSTMENT_FLOOR.

raised class-attribute instance-attribute

raised: dict[AbilityScore, int] = {}

How much to add to each ability, as a positive number.

Only the class's prime requisites may appear, the amounts must add up to half the points taken off, and no score may end above MAX_SCORE.

AbilityCheckResult

Bases: BaseModel

How an ability check turned out, including the die roll so you can show it.

ability_check returns one.

roll instance-attribute

roll: int

What the d20 came up, from 1 to 20, before the modifier.

score instance-attribute

score: int

The ability score the roll was checked against.

modifier instance-attribute

modifier: int

The difficulty modifier that was applied to the roll. Positive made it harder.

success instance-attribute

success: bool

Whether the check succeeded.

A natural 1 always succeeds and a natural 20 always fails. Otherwise the check succeeds when the roll plus the modifier is at or under the score.

AbilityScore

Bases: StrEnum

Which of the six abilities a score belongs to.

Use these as the keys of a score dictionary, which is how every function here and in osrlib.core.character passes a character's abilities around. Include all six keys: a Character raises a pydantic ValidationError for a score dictionary that's missing one.

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

STR class-attribute instance-attribute

STR = 'str'

Strength: melee attack and damage, and the chance to force a stuck door open.

INT class-attribute instance-attribute

INT = 'int'

Intelligence: how many extra languages a character speaks, and whether they can read and write.

WIS class-attribute instance-attribute

WIS = 'wis'

Wisdom: the modifier on saving throws against magical effects.

DEX class-attribute instance-attribute

DEX = 'dex'

Dexterity: armour class, missile attacks, and initiative under the individual-initiative rule.

CON class-attribute instance-attribute

CON = 'con'

Constitution: the hit points added to each Hit Die rolled.

CHA class-attribute instance-attribute

CHA = 'cha'

Charisma: how monsters and NPCs react, and how many retainers the character can keep, and how loyal they are.

AbilityTables

Bases: BaseModel

The SRD's ability tables, and the accessors that read a score out of them.

Get one from load_ability_tables, which loads the tables that come with the package and caches them, so calling it again costs nothing. Then call the accessor for the column you want, passing a score from MIN_SCORE to MAX_SCORE. A score outside that range raises ValueError, because it's a mistake in your code, not an outcome the rules allow.

A Character reads these tables for you and offers the results as properties, so use the accessors when you have a bare score and no character.

The fields contain the raw rows. Read them to draw a table, and use the accessors to play.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.melee_modifier(18) == 3
assert tables.hit_point_modifier(3) == -3

# The rows are there when you want to show the whole table.
assert (tables.strength[1].min_score, tables.strength[1].max_score) == (4, 5)

strength instance-attribute

strength: tuple[StrengthRow, ...]

The strength table's rows, lowest score first, together covering 3 to 18 with no gaps.

intelligence instance-attribute

intelligence: tuple[IntelligenceRow, ...]

The intelligence table's rows, lowest score first, together covering 3 to 18 with no gaps.

wisdom instance-attribute

wisdom: tuple[WisdomRow, ...]

The wisdom table's rows, lowest score first, together covering 3 to 18 with no gaps.

dexterity instance-attribute

dexterity: tuple[DexterityRow, ...]

The dexterity table's rows, lowest score first, together covering 3 to 18 with no gaps.

constitution instance-attribute

constitution: tuple[ConstitutionRow, ...]

The constitution table's rows, lowest score first, together covering 3 to 18 with no gaps.

charisma instance-attribute

charisma: tuple[CharismaRow, ...]

The charisma table's rows, lowest score first, together covering 3 to 18 with no gaps.

prime_requisite instance-attribute

prime_requisite: tuple[PrimeRequisiteRow, ...]

The prime requisite experience table's rows, lowest score first, together covering 3 to 18 with no gaps.

melee_modifier

melee_modifier(score: int) -> int

Return what a strength score adds to melee attack rolls and melee damage.

Missile attacks take the dexterity modifier instead. See missile_modifier.

Parameters:

Name Type Description Default
score int

A strength score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −3 at a score of 3 to +3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A strength of 16 adds 2 to a melee attack roll and to its damage.
assert tables.melee_modifier(16) == 2
assert tables.melee_modifier(5) == -2

open_doors_chance

open_doors_chance(score: int) -> int

Return the chance in 6 that a character with this strength forces a stuck door open.

Pass the result to open_doors_check, which rolls against it.

Parameters:

Name Type Description Default
score int

A strength score from 3 to 18.

required

Returns:

Type Description
int

The chance in 6, from 1 at a score of 3 to 5 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A strength of 16 forces a stuck door on a 1 to 4 on a d6.
assert tables.open_doors_chance(16) == 4
assert tables.open_doors_chance(9) == 2

additional_languages

additional_languages(score: int) -> int

Return how many languages beyond the native ones an intelligence score grants.

validate_extra_languages checks the choices themselves, and it reads this same allowance.

Parameters:

Name Type Description Default
score int

An intelligence score from 3 to 18.

required

Returns:

Type Description
int

The count, 0 below a score of 13 and up to 3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# An intelligence of 16 lets the character pick two languages at creation.
assert tables.additional_languages(16) == 2
assert tables.additional_languages(12) == 0

literacy

literacy(score: int) -> Literacy

Return how well an intelligence score lets a character read and write.

Parameters:

Name Type Description Default
score int

An intelligence score from 3 to 18.

required

Returns:

Type Description
Literacy

The Literacy band for that score.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.core.abilities import Literacy
from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.literacy(7) is Literacy.BASIC
assert tables.literacy(9) is Literacy.LITERATE

magic_save_modifier

magic_save_modifier(score: int) -> int

Return what a wisdom score adds to saving throws against magical effects.

It applies to magical effects only, not to a saving throw against a trap or a dragon's breath.

Parameters:

Name Type Description Default
score int

A wisdom score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −3 at a score of 3 to +3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A wisdom of 13 adds 1 to a save against a spell.
assert tables.magic_save_modifier(13) == 1
assert tables.magic_save_modifier(3) == -3

ac_modifier

ac_modifier(score: int) -> int

Return what a dexterity score is worth to armour class.

The number is a bonus. Subtract it from a descending armour class, where lower is better, or add it to an ascending one. Character.armour_class applies it for you.

Parameters:

Name Type Description Default
score int

A dexterity score from 3 to 18.

required

Returns:

Type Description
int

The bonus, from −3 at a score of 3 to +3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A dexterity of 17 improves a descending armour class of 7 to 5.
assert 7 - tables.ac_modifier(17) == 5

missile_modifier

missile_modifier(score: int) -> int

Return what a dexterity score adds to missile attack rolls.

It changes the attack roll only. Missile damage takes no ability modifier.

Parameters:

Name Type Description Default
score int

A dexterity score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −3 at a score of 3 to +3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.missile_modifier(13) == 1
assert tables.missile_modifier(6) == -1

initiative_modifier

initiative_modifier(score: int) -> int

Return what a dexterity score adds to an individual initiative roll.

osrlib uses it only when the individual_initiative flag on Ruleset is on. With the flag off, each side rolls initiative once and no ability modifier applies.

Parameters:

Name Type Description Default
score int

A dexterity score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −2 at a score of 3 to +2 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# Under individual initiative, a dexterity of 18 adds 2 to the d6.
assert tables.initiative_modifier(18) == 2
assert tables.initiative_modifier(16) == 1

hit_point_modifier

hit_point_modifier(score: int) -> int

Return what a constitution score adds to every Hit Die a character rolls.

It applies to the first-level die and to each die a new level adds. However negative it is, a die gives at least 1 hit point. Levels past name level add a fixed number of hit points instead of a die, and the modifier doesn't apply to them.

Parameters:

Name Type Description Default
score int

A constitution score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −3 at a score of 3 to +3 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A constitution of 14 adds 1 to each Hit Die.
assert tables.hit_point_modifier(14) == 1
assert tables.hit_point_modifier(4) == -2

npc_reaction_modifier

npc_reaction_modifier(score: int) -> int

Return what a charisma score adds to a monster or NPC reaction roll.

Add it to the 2d6 total before reading the result with reaction_result, which reads a total below 2 as the lowest band and a total above 12 as the highest.

Parameters:

Name Type Description Default
score int

A charisma score from 3 to 18.

required

Returns:

Type Description
int

The modifier, from −2 at a score of 3 to +2 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.npc_reaction_modifier(18) == 2
assert tables.npc_reaction_modifier(10) == 0

max_retainers

max_retainers(score: int) -> int

Return how many hired followers a charisma score lets a character keep at once.

osrlib has no rules for retainers, so applying this number is up to you.

Parameters:

Name Type Description Default
score int

A charisma score from 3 to 18.

required

Returns:

Type Description
int

The count, from 1 at a score of 3 to 7 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.max_retainers(10) == 4
assert tables.max_retainers(18) == 7

retainer_loyalty

retainer_loyalty(score: int) -> int

Return the loyalty a retainer of a character with this charisma score starts with.

In the SRD, the referee rolls a loyalty check against this score when a retainer is asked to do something risky. osrlib has no rules for retainers, so applying the number is up to you.

Parameters:

Name Type Description Default
score int

A charisma score from 3 to 18.

required

Returns:

Type Description
int

The loyalty score, from 4 at a charisma of 3 to 10 at 18.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()
assert tables.retainer_loyalty(10) == 7
assert tables.retainer_loyalty(18) == 10

prime_requisite_xp_modifier_pct

prime_requisite_xp_modifier_pct(score: int) -> int

Return the percentage a single prime requisite score changes earned experience by.

A prime requisite is the ability a class is built around. This table covers a class with exactly one. A class with more than one has separate tiers on its class definition, and xp_modifier_pct picks the right source for you.

Parameters:

Name Type Description Default
score int

A prime requisite score from 3 to 18.

required

Returns:

Type Description
int

The percentage, from −20 at a score of 3 to +10 at 16 or above.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.data import load_ability_tables

tables = load_ability_tables()

# A fighter with strength 13 earns 5% more experience: 105 points for 100.
pct = tables.prime_requisite_xp_modifier_pct(13)
assert pct == 5
assert 100 * (100 + pct) // 100 == 105

CharismaRow

Bases: ScoreBand

One row of the charisma table: a band of scores, with its reaction modifier and retainer limits.

Read the rows from AbilityTables.charisma to draw the table. To look up one score, call npc_reaction_modifier, max_retainers, or retainer_loyalty instead.

npc_reactions instance-attribute

npc_reactions: int

What to add to the reaction roll that sets how monsters or NPCs respond when they meet the party.

max_retainers class-attribute instance-attribute

max_retainers: int = Field(ge=0)

How many retainers, hired followers, the character may have at once. osrlib's rules don't use it.

retainer_loyalty class-attribute instance-attribute

retainer_loyalty: int = Field(ge=0)

The loyalty score a retainer of this character starts with. osrlib's rules don't use it.

ConstitutionRow

Bases: ScoreBand

One row of the constitution table: a band of scores, with its hit point modifier.

Constitution grants no other bonus. Read the rows from AbilityTables.constitution to draw the table. To look up one score, call hit_point_modifier instead.

hit_points instance-attribute

hit_points: int

What to add to each Hit Die rolled, at creation and when a new level adds a die.

However negative this is, a die gives at least 1 hit point. Levels past name level add a fixed number of hit points instead of a die, and this modifier doesn't apply to them.

DexterityRow

Bases: ScoreBand

One row of the dexterity table: a band of scores, with its armour class, missile, and initiative modifiers.

Read the rows from AbilityTables.dexterity to draw the table. To look up one score, call ac_modifier, missile_modifier, or initiative_modifier instead.

ac instance-attribute

ac: int

The armour class bonus. Subtract it from a descending armour class, or add it to an ascending one.

missile instance-attribute

missile: int

What to add to a missile attack roll. It doesn't change missile damage.

initiative instance-attribute

initiative: int

What to add to an individual initiative roll.

It applies only when the individual_initiative flag on Ruleset is on. Otherwise each side rolls initiative once.

IntelligenceRow

Bases: ScoreBand

One row of the intelligence table: a band of scores, with its languages and literacy.

Read the rows from AbilityTables.intelligence to draw the table. To look up one score, call additional_languages or literacy instead.

additional_languages class-attribute instance-attribute

additional_languages: int = Field(ge=0)

How many languages beyond the character's native ones they may choose at creation.

literacy instance-attribute

literacy: Literacy

How well the character reads and writes. See Literacy.

broken_speech class-attribute instance-attribute

broken_speech: bool = False

True only at intelligence 3, where the character speaks their native language brokenly.

Literacy

Bases: StrEnum

How well a character reads and writes, which their intelligence score sets.

Read it off AbilityTables.literacy, passing the character's intelligence score. osrlib's rules don't use it. You decide what a character who can't read is unable to do, like reading a scroll, a map, or an inscription.

ILLITERATE class-attribute instance-attribute

ILLITERATE = 'illiterate'

Cannot read or write, at intelligence 5 or below.

BASIC class-attribute instance-attribute

BASIC = 'basic'

Basic literacy, at intelligence 6 to 8: the step the SRD prints between illiterate and literate.

LITERATE class-attribute instance-attribute

LITERATE = 'literate'

Can read and write the character's native languages, at intelligence 9 or above.

OpenDoorsResult

Bases: BaseModel

How an attempt to force a door turned out, including the die roll so you can show it.

open_doors_check returns one.

roll instance-attribute

roll: int

What the d6 came up, from 1 to 6.

chance instance-attribute

chance: int

The chance in 6 that was rolled against.

success instance-attribute

success: bool

Whether the attempt succeeded, which it does when the roll is at or under the chance.

PrimeRequisiteRow

Bases: ScoreBand

One row of the prime requisite table, which sets how fast a character earns experience.

A prime requisite is the ability a class is built around: wisdom for a cleric, strength for a fighter. This table applies to a class with a single prime requisite. A class with more than one has separate tiers in its class definition, and xp_modifier_pct reads the right one for any class.

xp_modifier_pct instance-attribute

xp_modifier_pct: int

The percentage added to or taken off experience earned, from −20 at a score of 3 to +10 at 16 or above.

ScoreBand

Bases: BaseModel

The run of scores one table row covers, like 4 to 5.

The SRD prints its modifier tables in bands instead of one row per score, and osrlib stores them the same way. Each table's row model, like StrengthRow, is a band with that row's columns added. You read these when you read a whole table off AbilityTables, for example to draw the table on screen. To look up a single score, call an accessor instead.

min_score class-attribute instance-attribute

min_score: int = Field(ge=MIN_SCORE, le=MAX_SCORE)

The lowest score this row covers.

max_score class-attribute instance-attribute

max_score: int = Field(ge=MIN_SCORE, le=MAX_SCORE)

The highest score this row covers. Equal to min_score on a one-score row.

StrengthRow

Bases: ScoreBand

One row of the strength table: a band of scores, with its melee modifier and open-doors chance.

Read the rows from AbilityTables.strength to draw the table. To look up one score, call melee_modifier or open_doors_chance instead.

melee instance-attribute

melee: int

What to add to a melee attack roll and to melee damage. Negative at a low score.

open_doors class-attribute instance-attribute

open_doors: int = Field(ge=0, le=6)

The chance in 6 of forcing a stuck door open.

Pass it to open_doors_check, which rolls the die against it.

WisdomRow

Bases: ScoreBand

One row of the wisdom table: a band of scores, with its saving throw modifier.

Wisdom grants no other bonus. Read the rows from AbilityTables.wisdom to draw the table. To look up one score, call magic_save_modifier instead.

magic_saves instance-attribute

magic_saves: int

What to add to a saving throw against a magical effect. Negative at a low score.

ability_check

ability_check(score: int, stream: RngStream, modifier: int = 0) -> AbilityCheckResult

Roll an ability check: 1d20, equal-or-under the score succeeds.

Use this for a task the rules don't cover with a specific procedure: shoving a boulder, spotting a change in the stonework, holding a rope. Pick the ability that fits and set the difficulty with modifier. For the things the rules do cover, call the function that covers them: open_doors_check for a stuck door, saving_throw for magic and traps, and thief_skill_check for a thief's skills.

The roll is a d20, and the check succeeds when the roll plus the modifier is at or under the score, so a character with a higher score succeeds more often. The SRD leaves the difficulty to the referee and suggests "a –4 modifier for an easy task or +4 for a difficult task". A natural 1 always succeeds and a natural 20 always fails, the opposite of an attack roll.

Parameters:

Name Type Description Default
score int

The ability score to check against, from 3 to 18.

required
stream RngStream

The stream to draw the d20 from.

required
modifier int

The difficulty, added to the roll. Positive makes the check harder.

0

Returns:

Type Description
AbilityCheckResult

The outcome, including the unmodified d20 roll for display.

Raises:

Type Description
ValueError

If score is outside 3 to 18.

Examples:

from osrlib.core.abilities import ability_check
from osrlib.core.rng import RngStreams

stream = RngStreams(master_seed=3).get("exploration")

# A roll of 18 is over the score of 13, so the check fails.
check = ability_check(13, stream)
assert (check.roll, check.success) == (18, False)

# A difficult task: +4 on the roll, so a 5 is still under 13.
harder = ability_check(13, stream, modifier=4)
assert (harder.roll, harder.success) == (5, True)

apply_adjustment

apply_adjustment(
    scores: dict[AbilityScore, int],
    adjustment: AbilityAdjustment,
    prime_requisites: tuple[AbilityScore, ...],
    may_not_lower: tuple[AbilityScore, ...] = (),
) -> dict[AbilityScore, int]

Apply a points trade and return the adjusted scores.

Call validate_adjustment first, with the same arguments. This function validates again and refuses to produce scores that break the rules, so an exception here means your code let an illegal trade through, not that the player chose badly. It applies the whole trade or nothing.

Pass the result as scores when you construct the Character yourself. You don't call this when you use create_character: it takes the AbilityAdjustment as its adjustment argument and applies it for you.

Parameters:

Name Type Description Default
scores dict[AbilityScore, int]

The rolled scores, with all six abilities present, each from 3 to 18. This dictionary isn't changed. The adjusted scores come back in a new one.

required
adjustment AbilityAdjustment

The trade to apply.

required
prime_requisites tuple[AbilityScore, ...]

The chosen class's prime requisites.

required
may_not_lower tuple[AbilityScore, ...]

Abilities this class forbids lowering.

()

Returns:

Type Description
dict[AbilityScore, int]

A new score dictionary with the points moved. It has the same keys as scores, and the abilities the trade didn't change have their rolled values.

Raises:

Type Description
ValueError

If the trade breaks any rule validate_adjustment checks. The message includes the rejection codes. Also if scores is missing an ability, or has a score below 3 or above 18, as validate_adjustment raises.

Examples:

from osrlib.core.abilities import AbilityAdjustment, AbilityScore, apply_adjustment

scores = {
    AbilityScore.STR: 9,
    AbilityScore.INT: 13,
    AbilityScore.WIS: 12,
    AbilityScore.DEX: 11,
    AbilityScore.CON: 14,
    AbilityScore.CHA: 10,
}
adjustment = AbilityAdjustment(
    lowered={AbilityScore.INT: 2, AbilityScore.WIS: 2},
    raised={AbilityScore.STR: 2},
)

adjusted = apply_adjustment(scores, adjustment, (AbilityScore.STR,))
assert adjusted[AbilityScore.STR] == 11
assert adjusted[AbilityScore.INT] == 11
assert adjusted[AbilityScore.CON] == 14

# The rolled scores are untouched.
assert scores[AbilityScore.STR] == 9

open_doors_check

open_doors_check(chance: int, stream: RngStream) -> OpenDoorsResult

Roll one character's attempt to force a stuck door open.

Get the chance from AbilityTables.open_doors_chance for the character's strength. The attempt succeeds on a d6 roll at or under the chance. The function only rolls and reports the result. You apply the consequences: opening the door, and whatever else the attempt costs the party.

In a session, execute ForceDoor instead. It applies those consequences for you: the party makes noise, a success opens the door and springs any trap on it, and a failure alerts the area beyond, each with its events. Call this function when you work without a session.

Parameters:

Name Type Description Default
chance int

The chance in 6, from 0 to 6.

required
stream RngStream

The stream to draw the d6 from.

required

Returns:

Type Description
OpenDoorsResult

The outcome, including the d6 roll for display.

Raises:

Type Description
ValueError

If chance is outside 0 to 6.

Examples:

from osrlib.core.abilities import open_doors_check
from osrlib.core.rng import RngStreams
from osrlib.data import load_ability_tables

chance = load_ability_tables().open_doors_chance(16)
assert chance == 4

result = open_doors_check(chance, RngStreams(master_seed=3).get("exploration"))
assert (result.roll, result.success) == (5, False)

validate_adjustment

validate_adjustment(
    scores: dict[AbilityScore, int],
    adjustment: AbilityAdjustment,
    prime_requisites: tuple[AbilityScore, ...],
    may_not_lower: tuple[AbilityScore, ...] = (),
) -> list[Rejection]

Check a proposed points trade against the rules, and return what's wrong with it.

Call this before apply_adjustment and show the player what comes back. An empty list means the trade is legal. The two functions take the same four arguments, so you can pass the same ones to both.

The rules it enforces come from the SRD's third character-creation step. osrlib's interpretation of that step is in the adaptations register, the page that lists each place where osrlib chooses one interpretation of the rules. The rules are these:

  • Only strength, intelligence, and wisdom may be lowered.
  • A prime requisite of the chosen class may not be lowered, and neither may an ability the class forbids lowering, which is why a thief may not lower strength.
  • Each score comes down by an even amount, because osrlib works out the two-for-one trade per score, and an odd amount would leave half a point.
  • The points bought add up to half the points sold, and go only into the class's prime requisites.
  • No score is lowered below ADJUSTMENT_FLOOR or raised above MAX_SCORE.

Parameters:

Name Type Description Default
scores dict[AbilityScore, int]

The rolled scores, with all six abilities present, each from MIN_SCORE to MAX_SCORE.

required
adjustment AbilityAdjustment

The trade the player proposed.

required
prime_requisites tuple[AbilityScore, ...]

The chosen class's prime requisites, from ClassDefinition.

required
may_not_lower tuple[AbilityScore, ...]

Abilities this class forbids lowering, also from the class definition.

()

Returns:

Type Description
list[Rejection]

One Rejection per rule broken, empty when the trade is legal. A single proposal can break several rules at once, so expect more than one.

Raises:

Type Description
ValueError

If scores is missing an ability, or has a score below 3 or above 18. No character can roll such scores, so there's no trade to judge. The message includes the ability.

Examples:

from osrlib.core.abilities import AbilityAdjustment, AbilityScore, validate_adjustment

scores = {
    AbilityScore.STR: 9,
    AbilityScore.INT: 13,
    AbilityScore.WIS: 12,
    AbilityScore.DEX: 11,
    AbilityScore.CON: 14,
    AbilityScore.CHA: 10,
}

# Four points down, two points up, into the fighter's prime requisite.
legal = AbilityAdjustment(
    lowered={AbilityScore.INT: 2, AbilityScore.WIS: 2},
    raised={AbilityScore.STR: 2},
)
assert validate_adjustment(scores, legal, (AbilityScore.STR,)) == []

# Buying two points for two is not the rate.
greedy = AbilityAdjustment(lowered={AbilityScore.INT: 2}, raised={AbilityScore.STR: 2})
assert [rejection.code for rejection in validate_adjustment(scores, greedy, (AbilityScore.STR,))] == [
    "creation.adjustment.points_mismatch"
]