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,
ReorderPartysets the order. The session callsreorderwhen 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. AddMemberadds a new member at the back, andRemoveMembertakes 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
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
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 |
member
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 |
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
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
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
|
required |
Returns:
| Type | Description |
|---|---|
list[list[Character]]
|
The ranks, front first. The last rank contains the remainder and can be shorter than
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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
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. |