Skip to content

osrlib.crawl.party

The adventuring party: marching order, group movement, and combat ranks.

You build a Party from Character objects, usually ones create_character made, and pass it to GameSession.new with the adventure. From then on the session moves the party as one group. session.party is the same object you passed.

The order of the member list is the marching order, so the first member is the one in front. The list is the only record of the order.

In a fight, the front rank is the living members at the front of the marching order, as many as fit side by side. Only they can attack in melee. With the formation_width_limit ruleset flag off, every living member is in the front rank. ranks splits the party into ranks.

Three things change the list:

  • Outside a fight, ReorderParty sets the order. The session calls reorder when it accepts one.
  • In a battle, a member who makes a fighting withdrawal or a retreat alone trades places with the member named in BattleDeclaration.replacement_id. The new order lasts after the battle.
  • AddMember adds a new member at the back, and RemoveMember takes a member out for good. Both are referee commands, ones your game logic issues rather than a player.

Dead members stay in the list, with their gear still on them, until a RemoveMember takes them out. The rules that count party members skip the dead: movement rate, combat ranks, traps, and food and water all use living_members.

Party

Bases: BaseModel

The adventuring party, in marching order.

Construct one with at least one member and pass it to GameSession.new, which assigns each member an id and keeps the party for the life of the session. To add a member during play, execute AddMember. The methods return facts about the group as a whole: who is still alive, how fast the group walks, and who stands where in a fight.

A party is mutable. The session heals, wounds, and re-equips its members in place, and assigning a new list to members validates it. The list is never empty: when the last member dies, the session ends in game_over and the dead stay in the list.

Attributes:

Name Type Description
members list[Character]

The characters, front of the line first.

Examples:

from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.party import Party

rolled = {
    "name": "Hild",
    "class_id": "fighter",
    "race": "human",
    "level": 1,
    "xp": 0,
    "scores": {ability: 12 for ability in AbilityScore},
    "alignment": Alignment.LAWFUL,
    "max_hp": 8,
    "current_hp": 8,
}
party = Party(members=[Character(**rolled), Character(**{**rolled, "name": "Osric"})])
print([member.name for member in party.living_members()])
# ['Hild', 'Osric']

members class-attribute instance-attribute

members: list[Character] = Field(min_length=1)

The party's characters, in marching order: index 0 walks in front and meets whatever the party walks into first. At least one member is required. GameSession.new assigns ids when the party joins a session, so a member you just built has None as its id until then.

Don't change this list directly. Use a command, so the change is logged and a replay reproduces it:

  • To add a member during play, execute AddMember. It assigns the new member's id and puts them at the back.
  • To take a member out of play, execute RemoveMember.
  • To change the order outside a fight, execute ReorderParty.
  • In a battle, a member who withdraws alone names the member to trade places with in BattleDeclaration.replacement_id.

living_members

living_members() -> list[Character]

Return the living members, in marching order.

A member is living until they have the dead condition. Every rule that applies to the group uses this list, so a member who dies stops counting toward movement, ranks, and checks at once, without leaving the party.

A member turned to stone isn't dead, so they stay in this list and keep their rank. The session's game_over check asks a narrower question: whether any member is neither dead nor petrified.

Returns:

Type Description
list[Character]

The members without the dead condition, in marching order. Empty when every member is dead.

member

member(character_id: str) -> Character

Return the member with character_id.

Use this to turn an id from a command or an event into the character it refers to. Events identify characters by id, not by name. The ids come from GameSession.new, which gives each member an id like character-0001, in party order. AddMember gives a member who joins during play the next id. Inside a session, GameSession.member does the same lookup.

Parameters:

Name Type Description Default
character_id str

The member's id, like "character-0001".

required

Returns:

Type Description
Character

The character. Dead members are returned too, because their gear and their record are still the party's.

Raises:

Type Description
ValueError

If no member has that id. The message includes the id.

Examples:

from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.adventure import Adventure, TownSpec
from osrlib.crawl.dungeon import DungeonSpec, LevelSpec
from osrlib.crawl.party import Party
from osrlib.crawl.session import GameSession

members = [
    Character(
        name=name,
        class_id="fighter",
        race="human",
        level=1,
        xp=0,
        scores={ability: 12 for ability in AbilityScore},
        alignment=Alignment.LAWFUL,
        max_hp=8,
        current_hp=8,
    )
    for name in ("Hild", "Osric")
]
level = LevelSpec(number=1, width=1, height=1, entrance=(0, 0))
crypt = DungeonSpec(id="crypt", name="The Old Crypt", levels=(level,))
adventure = Adventure(name="A First Delve", town=TownSpec(name="Threshold"), dungeons=(crypt,))
session = GameSession.new(Party(members=members), adventure, seed=7)

# Ids come from the session; an event about the second member carries "character-0002".
print(session.party.member("character-0002").name)
# Osric

movement_rate

movement_rate(ruleset: Ruleset) -> int

Return the party's exploration rate, which is the slowest living member's rate.

B/X moves a group at the pace of its slowest member, so one overloaded character slows everybody. Call Character.movement_rate for one character's rate. For the rate a running session uses, call exploration_rate. It takes the same minimum, but first halves the rate of a member who has gone too long without food or water, when the deprivation_penalties ruleset option is on.

Parameters:

Name Type Description Default
ruleset Ruleset

The ruleset whose encumbrance option applies. Encumbrance is the rule that turns what a character carries into a movement rate, and the options differ in what they count.

required

Returns:

Type Description
int

The rate in feet per exploration turn: 120, 90, 60, 30, or 0. A rate of 0 means the party cannot move at all, either because its slowest living member is overloaded or because nobody is alive to walk.

Examples:

from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.core.ruleset import Ruleset
from osrlib.crawl.party import Party

hild = Character(
    name="Hild",
    class_id="fighter",
    race="human",
    level=1,
    xp=0,
    scores={ability: 12 for ability in AbilityScore},
    alignment=Alignment.LAWFUL,
    max_hp=8,
    current_hp=8,
)
party = Party(members=[hild])
print(party.movement_rate(Ruleset()))
# 120

ranks

ranks(width: int) -> list[list[Character]]

Chunk the living members into combat ranks of width, in marching order.

A rank is one row of the formation. The first width living members stand in front and fight in melee, and the rest stand behind them. During a battle, the session calls this with a width it works out from the space the party stands in, so you rarely choose a width yourself. Call it to draw the formation, or to find out who is in front outside a fight.

The ranks aren't stored. Each call works them out again, so when a front-rank member dies, the next living member is in front from the next call on.

Parameters:

Name Type Description Default
width int

How many characters stand side by side. In a battle, the session works this out from the width of the space the party stands in (see FIGHTER_FRONTAGE_FEET) while the formation_width_limit ruleset option is on, and puts the whole party in one rank when it's off.

required

Returns:

Type Description
list[list[Character]]

The ranks, front first. The last rank contains the remainder and can be shorter than width. Empty when nobody is alive.

Raises:

Type Description
ValueError

If width is not positive.

Examples:

from osrlib.core.abilities import AbilityScore
from osrlib.core.alignment import Alignment
from osrlib.core.character import Character
from osrlib.crawl.party import Party

members = [
    Character(
        name=name,
        class_id="fighter",
        race="human",
        level=1,
        xp=0,
        scores={ability: 12 for ability in AbilityScore},
        alignment=Alignment.LAWFUL,
        max_hp=8,
        current_hp=8,
    )
    for name in ("Hild", "Osric", "Brand")
]
party = Party(members=members)
for number, rank in enumerate(party.ranks(2), start=1):
    print(number, [member.name for member in rank])
# 1 ['Hild', 'Osric']
# 2 ['Brand']

reorder

reorder(character_ids: Sequence[str]) -> None

Rewrite the marching order in place.

The session calls this when it accepts a ReorderParty command. Execute that command with GameSession.execute rather than calling this method yourself, so the change is logged and a replay reproduces it.

Parameters:

Name Type Description Default
character_ids Sequence[str]

Every member's id, in the new order. It must list each current member exactly once, with no other ids. Include the dead members, because they're still in the party.

required

Raises:

Type Description
ValueError

If the ids aren't exactly the current members' ids, or if any member has no id yet because the party hasn't joined a session. The order doesn't change.