osrlib 2.1.0__tar.gz → 2.2.0__tar.gz

{osrlib-2.1.0 → osrlib-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osrlib
-Version: 2.1.0
+Version: 2.2.0
 Summary: B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers
 Keywords: basic-expert,bx,dungeon-crawler,game-engine,osr,rpg,srd,ttrpg
 Author: Marsh Macy

{osrlib-2.1.0 → osrlib-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "osrlib"
-version = "2.1.0"
+version = "2.2.0"
 description = "B/X (1981 Basic/Expert) tabletop RPG rules engine for turn-based dungeon crawlers"
 readme = "README.md"
 # The wheel ships Open Game Content (osrlib/data/*.json and its LICENSE-OGL.md

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/core/combat.py

@@ -380,13 +380,16 @@ class AttackContext(BaseModel):
     """Whether the attacker strikes from behind.
 
     The defender's shield doesn't count. With `target_unaware`, a thief attacker gets the
-    back-stab bonus to hit and to damage.
+    back-stab bonus to hit and to damage, and the attack's
+    [`AttackRolledEvent`][osrlib.core.events.AttackRolledEvent] has `back_stab` set.
     """
 
     target_unaware: bool = False
     """Whether the defender is unaware of the attack.
 
-    With `behind_target`, a thief attacker gets the back-stab bonus to hit and to damage.
+    With `behind_target`, a thief attacker gets the back-stab bonus to hit and to damage, and
+    the attack's [`AttackRolledEvent`][osrlib.core.events.AttackRolledEvent] has `back_stab`
+    set.
     """
 
     defender_retreating: bool = False
@@ -1399,7 +1402,8 @@ def attack_roll(
       modifier from the context's `distance_feet`, and, for a halfling attacker, the
       halfling's missile bonus.
     - A thief's back-stab bonus, when the context sets both `behind_target` and
-      `target_unaware`.
+      `target_unaware`. The event's `back_stab` field is then true, on an automatic hit
+      too.
     - +2 against a retreating defender.
     - A magic weapon's attack bonus, or its bonus against the kind of monster it's made
       against.
@@ -1478,12 +1482,16 @@ def attack_roll(
     name = _attack_name(attack)
     missile = _is_missile_use(attack, context) or (isinstance(attack, MonsterAttack) and context.monster_missile)
     helpless = not missile and any(has_condition(defender, condition) for condition in _HELPLESS)
+    back_stab = (
+        _class_ability_params(attacker, "back_stab") if context.behind_target and context.target_unaware else None
+    )
     if helpless or getattr(defender, "armour_class", 0) is None:
         event = AttackRolledEvent(
             code="combat.attack.auto_hit",
             attacker_id=attacker_id,
             defender_id=defender_id,
             attack_name=name,
+            back_stab=back_stab is not None,
         )
         return AttackRollResult(hit=True, auto=True, events=(event,))
 
@@ -1497,10 +1505,8 @@ def attack_roll(
             modifier += int(halfling.get("bonus", 0))
     else:
         modifier += melee_modifier_for(attacker)
-    if context.behind_target and context.target_unaware:
-        back_stab = _class_ability_params(attacker, "back_stab")
-        if back_stab is not None:
-            modifier += int(back_stab.get("attack_bonus", 0))
+    if back_stab is not None:
+        modifier += int(back_stab.get("attack_bonus", 0))
     if context.defender_retreating:
         modifier += 2
     # An enchanted arm's bonus (versus-clauses swapping in their alternate).
@@ -1548,6 +1554,7 @@ def attack_roll(
         required=required,
         defender_ac=ac,
         natural=natural_override,
+        back_stab=back_stab is not None,
     )
     return AttackRollResult(
         hit=hit,

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/core/events.py

@@ -340,6 +340,16 @@ class AttackRolledEvent(Event):
     A natural 20 always hits and a natural 1 always misses. This field is set only when that rule changed the
     outcome: a 20 whose total was below `required`, or a 1 whose total reached it."""
 
+    back_stab: bool = False
+    """True when the attack was a thief's back-stab, so your game can say so.
+
+    [`attack_roll`][osrlib.core.combat.attack_roll] sets it when the attack's
+    [`AttackContext`][osrlib.core.combat.AttackContext] sets both `behind_target` and `target_unaware`, and the
+    attacker's class has the `back_stab` ability. The back-stab's bonus to hit is part of `modifier`, and the damage
+    that follows is doubled. It's true on an automatic hit too, because the damage still doubles. A
+    [`GameSession`][osrlib.crawl.session.GameSession] makes that attack for a member who declares
+    [`BattleDeclaration.back_stab`][osrlib.crawl.commands.BattleDeclaration.back_stab]."""
+
 
 class DamageDealtEvent(Event):
     """Damage dealt to a creature.

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/crawl/battle.py

@@ -1784,6 +1784,33 @@ def _projected_front_rank(session, plan: Sequence[_Withdrawal]) -> set[str]:
     return set(order if width is None else order[:width])
 
 
+def _back_stab_rejection(session, declaration: BattleDeclaration, member) -> Rejection | None:
+    """Return the first back-stab check a declaration fails before its action's own checks, or `None`.
+
+    A declaration without `back_stab` passes. Otherwise the checks run in this order, and each
+    rejection has the member's id as its `character` param:
+
+    1. `battle.declaration.back_stab_not_attack`: the action isn't `attack`.
+    2. `battle.declaration.back_stab_no_ability`: the member's class has no `back_stab` ability.
+    3. `battle.declaration.back_stab_target_aware`: the monsters aren't held by the party's surprise,
+       so [`BattleState.monsters_hold_rounds`][osrlib.crawl.battle.BattleState.monsters_hold_rounds]
+       is zero.
+
+    The pre-phase reads `monsters_hold_rounds` before the monster block of the round spends it, so a
+    back-stab accepted in the free round stays a back-stab for every attack roll of that round.
+    """
+    if not declaration.back_stab:
+        return None
+    params = {"character": member.id}
+    if declaration.action != "attack":
+        return Rejection(code="battle.declaration.back_stab_not_attack", params=params)
+    if not any(ability.tag == "back_stab" for ability in member.definition.abilities):
+        return Rejection(code="battle.declaration.back_stab_no_ability", params=params)
+    if session.battle.monsters_hold_rounds <= 0:
+        return Rejection(code="battle.declaration.back_stab_target_aware", params=params)
+    return None
+
+
 def _validate_declaration(
     session, declaration: BattleDeclaration, member, *, front_rank: set[str] | None = None
 ) -> list[Rejection]:
@@ -1809,8 +1836,16 @@ def _validate_declaration(
     with no such monster left gets `battle.declaration.no_target`, with the member's id as the
     `character` param. Only the magic phase's second run can meet that. The check doesn't ask
     whether any monster is undead, so a refusal never tells the player which monsters are undead.
+
+    A declaration that sets `back_stab` gets the back-stab checks of `_back_stab_rejection` before
+    any other check. On an attack, `battle.declaration.back_stab_not_melee` comes after the group and
+    weapon checks and before the melee checks, as
+    [`BattleDeclaration.back_stab`][osrlib.crawl.commands.BattleDeclaration.back_stab] gives the order.
     """
     state = session.battle
+    refused = _back_stab_rejection(session, declaration, member)
+    if refused is not None:
+        return [refused]
     if declaration.action == "hold":
         return []
     if declaration.action == "move":
@@ -1836,6 +1871,8 @@ def _validate_declaration(
         if declaration.weapon_id is not None and weapon is None:
             return [Rejection(code="battle.declaration.weapon_not_wielded", params={"item": declaration.weapon_id})]
         missile = _is_missile_declaration(weapon, group.distance_feet)
+        if declaration.back_stab and missile:
+            return [Rejection(code="battle.declaration.back_stab_not_melee", params={"character": member.id})]
         if not missile:
             width = _formation_width(session)
             if front_rank is None:
@@ -2303,7 +2340,15 @@ def _handle_resolve_battle_round(session, command: ResolveBattleRound) -> tuple[
         rejections.extend(_validate_declaration(session, declaration, member, front_rank=front_rank))
         if declaration.gaze_defense == "mirror" and member.inventory.carried_item(_MIRROR_ITEM_ID) is None:
             rejections.append(Rejection(code="battle.declaration.no_mirror", params={"character": member.id}))
-    rejections.extend(withdrawal_rejections)
+    # A move that sets `back_stab` gets `back_stab_not_attack` in place of its own withdrawal checks.
+    back_stabbers = {
+        member.id
+        for member, declaration in by_member.values()
+        if declaration.back_stab and declaration.action != "attack"
+    }
+    rejections.extend(
+        rejection for rejection in withdrawal_rejections if rejection.params.get("character") not in back_stabbers
+    )
     if rejections:
         # The session rejects the whole command and lists every rejection. Partial
         # acceptance would complicate replay (see the adaptations register).
@@ -2616,6 +2661,9 @@ def _resolve_party_attack(session, member, declaration, fired, fire_damaged) ->
             situational_modifier=_gaze_stance_modifier(member, declaration),
             fired_last_round=member.id in state.fired_last_round,
             defender_retreating=group.fleeing,
+            # An accepted back-stab stays one for every swing of the round, after the held turn too.
+            behind_target=declaration.back_stab,
+            target_unaware=declaration.back_stab,
         )
         result = resolve_attack(
             member,

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/crawl/commands.py

@@ -33,7 +33,7 @@ an item or spawning monsters.
 Game logic issues referee commands, not the players. The issuer can be a
 [`Listener`][osrlib.crawl.session.Listener] you write, the interpreter that runs an
 adventure's triggers, or an LLM referee. Referee commands grant and take away items and coins, award
-XP, add party members, set flags, spawn monsters, end encounters, move the clock, and record
+XP, add and remove party members, set flags, spawn monsters, end encounters, move the clock, and record
 quest progress. Each one's summary starts with "Referee:". The session logs and replays them
 like any other command. Most referee commands are legal in every mode. These are the
 exceptions:
@@ -45,7 +45,8 @@ exceptions:
   `victory`, for the same reason.
 - [`EndEncounter`][osrlib.crawl.commands.EndEncounter] is legal only in `encounter` and
   `battle`, because it closes the open encounter.
-- [`AddMember`][osrlib.crawl.commands.AddMember] is legal only in `town` and `exploring`.
+- [`AddMember`][osrlib.crawl.commands.AddMember] and
+  [`RemoveMember`][osrlib.crawl.commands.RemoveMember] are legal only in `town` and `exploring`.
 
 Each command class's docstring states its contract in three sections. `Modes:` lists the session
 modes that accept it, `Rejections:` lists the codes it can be refused with, and `Events:`
@@ -101,6 +102,7 @@ The commands, grouped by what the party is doing:
   [`RemoveItem`][osrlib.crawl.commands.RemoveItem],
   [`RemoveCoins`][osrlib.crawl.commands.RemoveCoins],
   [`AddMember`][osrlib.crawl.commands.AddMember],
+  [`RemoveMember`][osrlib.crawl.commands.RemoveMember],
   [`AwardXP`][osrlib.crawl.commands.AwardXP],
   [`IdentifyItem`][osrlib.crawl.commands.IdentifyItem],
   [`SetFlag`][osrlib.crawl.commands.SetFlag],
@@ -233,6 +235,7 @@ __all__ = [
     "RecordNote",
     "RemoveCoins",
     "RemoveItem",
+    "RemoveMember",
     "RemoveTreasureTrap",
     "ReorderParty",
     "ResolveBattleRound",
@@ -288,6 +291,8 @@ class SessionMode(StrEnum):
       restart play.
     - [`EndEncounter`][osrlib.crawl.commands.EndEncounter] is illegal in both, because it
       needs an open encounter.
+    - [`RemoveMember`][osrlib.crawl.commands.RemoveMember] is illegal in both, because the
+      party changes only between encounters in a game that is still going.
 
     No play command leaves a terminal mode. A referee's `PlaceParty` is the only way out of
     `game_over`, and no command leaves `victory`.
@@ -389,8 +394,9 @@ class Command(BaseModel):
     [`SpawnMonsters`][osrlib.crawl.commands.SpawnMonsters],
     [`SpawnNpcParty`][osrlib.crawl.commands.SpawnNpcParty],
     [`PlaceParty`][osrlib.crawl.commands.PlaceParty],
-    [`EndEncounter`][osrlib.crawl.commands.EndEncounter], and
-    [`AddMember`][osrlib.crawl.commands.AddMember]. Each command's `Modes:` section lists
+    [`EndEncounter`][osrlib.crawl.commands.EndEncounter],
+    [`AddMember`][osrlib.crawl.commands.AddMember], and
+    [`RemoveMember`][osrlib.crawl.commands.RemoveMember]. Each command's `Modes:` section lists
     its modes."""
 
     @classmethod
@@ -2473,9 +2479,10 @@ class BattleDeclaration(BaseModel):
 
     `action` decides which other fields apply. Leave the others at their defaults.
 
-    - `attack` uses `target_group_id` and, optionally, `weapon_id`. With no `weapon_id`, the
-      member attacks with the wielded weapon that suits the attack, or with bare hands when
-      they wield none.
+    - `attack` uses `target_group_id` and, optionally, `weapon_id` and `back_stab`. With no
+      `weapon_id`, the member attacks with the wielded weapon that suits the attack, or with
+      bare hands when they wield none. Set `back_stab` for a thief's melee attack in the free
+      round the party gets when it surprises the monsters.
     - `cast` uses `spell_id`, `spell_mode`, `reversed`, and `targets`. `spell_id` is a spell
       id, like `"sleep"`. `spell_mode` is the key of one of the spell's modes, and `reversed`
       picks the spell's reversed form.
@@ -2705,6 +2712,51 @@ class BattleDeclaration(BaseModel):
     basilisk meet its gaze" says. No guard protects against that gaze.
     [The adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) describes the
     gaze in full."""
+    back_stab: bool = False
+    """Make this `attack` a back-stab, or leave it `False` for an ordinary attack.
+
+    The OSE SRD's thief entry says "When attacking an unaware opponent from behind, a thief
+    receives a +4 bonus to hit and doubles any damage dealt." osrlib has no facing in battle, so
+    the session reads an unaware opponent from behind as a monster the party surprised, in the
+    round it can't act. Set this field only when all of these are true:
+
+    - The action is `attack`.
+    - The member's class has the `back_stab` ability, as a thief's does.
+    - The monsters can't act this round because the party surprised them. That's the party's
+      free round, while
+      [`BattleState.monsters_hold_rounds`][osrlib.crawl.battle.BattleState.monsters_hold_rounds]
+      is above zero. The session reads it when it accepts the round.
+    - The attack is a melee attack. The weapon and the group's distance decide that, as
+      [`weapon_id`][osrlib.crawl.commands.BattleDeclaration.weapon_id] describes.
+
+    An accepted back-stab hits the same monster an ordinary melee attack would. It gets +4 to
+    hit, the defender's shield doesn't count, and its damage is doubled. The bonus and the
+    doubling come from the class's `back_stab` ability. Every attack roll the declaration makes
+    in the round is a back-stab, even when the monsters win initiative, and the attack's
+    [`AttackRolledEvent`][osrlib.core.events.AttackRolledEvent] has `back_stab` set to true, so
+    your game can say so.
+
+    The session refuses a back-stab with the first of these that applies, in this order. Each
+    of the four back-stab codes has the member's id as its `character` param.
+
+    1. `battle.declaration.back_stab_not_attack`: the action isn't `attack`. The session checks
+       this before any other check on the declaration.
+    2. `battle.declaration.back_stab_no_ability`: the member's class has no `back_stab` ability.
+    3. `battle.declaration.back_stab_target_aware`: the monsters aren't surprised this round.
+       That's every round of a battle the party didn't open by surprising the monsters, and
+       every round after the free round.
+    4. The checks of an ordinary attack on its group and weapon:
+       `battle.declaration.unknown_group`, `battle.declaration.no_target`, and
+       `battle.declaration.weapon_not_wielded`.
+    5. `battle.declaration.back_stab_not_melee`: the attack the session would resolve is a
+       missile attack. That's a missile weapon like a bow, or a weapon that's both melee and
+       missile, like a dagger, aimed at a group farther away than 5'.
+    6. The rest of an ordinary melee attack's checks, like
+       `battle.declaration.not_in_front_rank` and `combat.attack.out_of_reach`.
+
+    A declaration that leaves this field `False` resolves exactly as it would without it.
+    [The adaptations register](https://mmacy.github.io/osrlib-python/adaptations/) describes the
+    back-stab in full."""
 
 
 class ResolveBattleRound(Command):
@@ -2765,6 +2817,15 @@ class ResolveBattleRound(Command):
           `combat.attack.out_of_reach`, `combat.attack.out_of_range`,
           `combat.attack.reload`, `combat.attack.attacker_incapacitated`, and
           `combat.attack.attacker_blind`.
+        - A declaration that sets `back_stab`: `battle.declaration.back_stab_not_attack` on
+          any action but `attack`, before any other check. On an attack,
+          `battle.declaration.back_stab_no_ability` and
+          `battle.declaration.back_stab_target_aware` before the attack checks, and
+          `battle.declaration.back_stab_not_melee` after the group and weapon checks and
+          before the melee checks. A back-stab gets only the first of these that applies,
+          and each has the member's id as its `character` param.
+          [`BattleDeclaration.back_stab`][osrlib.crawl.commands.BattleDeclaration.back_stab]
+          gives the order in full.
         - Cast declarations: `battle.declaration.missing_spell`,
           `battle.declaration.unknown_group`,
           `battle.declaration.invisible_target`, and the cast checks
@@ -3143,7 +3204,8 @@ class AddMember(Command):
     [`ReorderParty`][osrlib.crawl.commands.ReorderParty], which is legal in the same modes. The
     session logs the command, so a saved game and a replay both have the new member.
 
-    The new id has the form `character-NNNN` and is unique in the party. Read it from the
+    The new id has the form `character-NNNN` and is unique in the party. It's never the id of a
+    member who left with [`RemoveMember`][osrlib.crawl.commands.RemoveMember]. Read it from the
     event, and pass it as the `character_id` of later commands. The session adds a copy of
     `character`, not the object you pass. Your object stays as it was, with no id. Read the new
     member with [`GameSession.member`][osrlib.crawl.session.GameSession.member].
@@ -3205,6 +3267,83 @@ class AddMember(Command):
         return value.model_copy(deep=True)
 
 
+class RemoveMember(Command):
+    """Referee: take a member out of the party for good.
+
+    Use it when a character leaves play: one who died too long ago for *raise dead*, a hireling
+    who quits, or a character the player retires. To bring in a replacement, send
+    [`AddMember`][osrlib.crawl.commands.AddMember] as well. The member can be in any state:
+    alive, dead, turned to stone, or asleep. The other members keep their marching order.
+
+    Name another member in `give_to` to keep what the leaving member carries in the party.
+    Every item and all the coins go to that member: mundane gear, magic items, gems, and
+    jewellery. Equipped items arrive unequipped in their pack, and an equipped magic item's
+    effects end, as with [`GiveItems`][osrlib.crawl.commands.GiveItems]. A cursed item moves
+    too, even when its curse is revealed, because the curse holds only its wearer, and the wearer
+    has left. It arrives with its curse hidden again, as *remove curse* leaves an item, so the
+    new owner can drop it or give it away. If they put it on, the curse is revealed again.
+    Without `give_to`, everything the member carries leaves the game with them.
+
+    The session also drops what it tracks about the member. The effects on them end without
+    events, and their death record, their food and water counts, and the record of when they
+    last prepared spells are deleted. An effect the member cast on another member lasts its full
+    duration. A light the member carried goes out with them. A burning torch leaves with its
+    bearer, and a lantern given to `give_to` arrives unlit. Read
+    [`GameSession.party_light`][osrlib.crawl.session.GameSession.party_light] afterwards to find
+    out whether the party still has light.
+
+    The member's id is retired. The session never gives it to another member, so an old event
+    that names it can't be mistaken for a new member. A replacement that joins with `AddMember`
+    gets a new id. The session refuses the old id in later commands with
+    `session.command.unknown_member`.
+
+    In a dungeon, the coins and valuables that leave with the member come off
+    [`treasure_snapshot_cp`][osrlib.crawl.session.GameSession.treasure_snapshot_cp], so the
+    departure doesn't change the experience the party earns for treasure when it comes back to
+    town. With `give_to`, nothing leaves the party, and the snapshot stays as it was.
+
+    Removing a member makes no draws and takes no time. The command is legal only in `town` and
+    `exploring`, like `AddMember`. The session never removes the last member who stands, which
+    means one who is neither dead nor turned to stone, because a party with nobody standing has
+    lost the game. To replace a player's last standing character, add the new character with
+    `AddMember` first, and then remove the old one.
+
+    Modes:
+        `town`, `exploring`
+
+    Rejections:
+        - `session.command.wrong_mode` - an encounter or a battle is open, or the session
+          has ended.
+        - `session.command.unknown_member` - `character_id` or `give_to` matches no party
+          member.
+        - `party.remove.same_member` - `give_to` names the member who leaves.
+        - `session.command.member_incapacitated` - the `give_to` member can't act, because
+          they're dead, asleep, paralysed, or turned to stone.
+        - `party.remove.last_standing` - no member would be left standing. That includes
+          removing the only member.
+
+        The session checks in this order and reports the first that fails.
+
+    Events:
+        With `give_to`, an [`EffectReleasedEvent`][osrlib.core.events.EffectReleasedEvent]
+        for each effect of an equipped magic item, then an
+        [`ItemsGivenEvent`][osrlib.crawl.events.ItemsGivenEvent] with what moved, when
+        anything did. Then a [`MemberRemovedEvent`][osrlib.crawl.events.MemberRemovedEvent]
+        with the member's id and name.
+    """
+
+    allowed_modes: ClassVar[frozenset[SessionMode]] = _FIELD_MODES
+
+    command_type: Literal["remove_member"] = "remove_member"
+    character_id: str
+    """The member who leaves, by [`MemberView.id`][osrlib.crawl.views.MemberView.id]. They can
+    be alive, dead, asleep, or turned to stone."""
+    give_to: str | None = None
+    """The member who takes everything the leaving member carries, by
+    [`MemberView.id`][osrlib.crawl.views.MemberView.id]. Leave it `None` to let it all leave the
+    game with the member. The member named here has to be able to act."""
+
+
 class AwardXP(Command):
     """Referee: give one character experience points, apart from the XP the session awards.
 
@@ -4066,6 +4205,7 @@ ALL_COMMAND_CLASSES: tuple[type[Command], ...] = (
     RemoveItem,
     RemoveCoins,
     AddMember,
+    RemoveMember,
 )
 """Every command class, in a fixed order. These are the members of the
 [`AnyCommand`][osrlib.crawl.commands.AnyCommand] union.
@@ -4140,6 +4280,9 @@ The other referee commands are left out for these reasons:
   so an authored roll would only use up draws from the adjudication stream.
 - [`AddMember`][osrlib.crawl.commands.AddMember] takes a whole character, and an adventure
   document doesn't contain characters.
+- [`RemoveMember`][osrlib.crawl.commands.RemoveMember] takes a player's character out of the
+  game, which is a decision for your game, not for an adventure. It can also name a member to
+  take the leaving member's goods, and no selector can name that member.
 
 In an authored consequence, the `character_id` of a grant, a removal, or an award is a
 selector, never a member id, because the session assigns member ids when it starts. The

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/crawl/events.py

@@ -123,6 +123,7 @@ __all__ = [
     "ListenedEvent",
     "LocationEnteredEvent",
     "MemberAddedEvent",
+    "MemberRemovedEvent",
     "MemberWithdrewEvent",
     "MonsterDefeatedEvent",
     "MonsterFledEvent",
@@ -2146,6 +2147,36 @@ class MemberAddedEvent(Event):
     """The new member's experience level when they joined."""
 
 
+class MemberRemovedEvent(Event):
+    """A member left the party during play.
+
+    Emitted by [`RemoveMember`][osrlib.crawl.commands.RemoveMember]. The member is already gone
+    from the party and from the views, so take them off the party on screen. When `given_to` is
+    set, the [`ItemsGivenEvent`][osrlib.crawl.events.ItemsGivenEvent] just before this event
+    lists what that member took. The event doesn't say why the member left. The command does:
+    read the `source` of the `RemoveMember`, either the one you executed or its entry in
+    [`GameSession.command_log`][osrlib.crawl.session.GameSession.command_log].
+    """
+
+    allowed_codes: ClassVar[frozenset[str]] = frozenset({"session.member.removed"})
+    """The only message code this event uses."""
+
+    event_type: Literal["member_removed"] = "member_removed"
+    """The event type, `member_removed`, which identifies this class in serialized form."""
+    code: str = "session.member.removed"
+    """The message code, always `session.member.removed`."""
+    visibility: Visibility = Visibility.PLAYER
+    """Player visibility: the players see who leaves them."""
+    character_id: str
+    """The id the member had, like `"character-0002"`. The session never gives it to another
+    member, so earlier events that name it still mean this character."""
+    name: str
+    """The member's name, so you can show the event without the member at hand."""
+    given_to: str | None = None
+    """The id of the member who took everything the leaving member carried, or `None` when it
+    all left the game with them."""
+
+
 CRAWL_EVENT_CLASSES: tuple[type[Event], ...] = (
     PartyMovedEvent,
     LocationEnteredEvent,
@@ -2206,6 +2237,7 @@ CRAWL_EVENT_CLASSES: tuple[type[Event], ...] = (
     AdventureCompletedEvent,
     ItemsRemovedEvent,
     MemberAddedEvent,
+    MemberRemovedEvent,
 )
 """The event classes defined in this module, in the order they're declared.
 

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/crawl/party.py

@@ -22,11 +22,12 @@ Three things change the list:
   the member named in
   [`BattleDeclaration.replacement_id`][osrlib.crawl.commands.BattleDeclaration.replacement_id].
   The new order lasts after the battle.
-- [`AddMember`][osrlib.crawl.commands.AddMember] adds a new member at the back. It's a referee
-  command, one your game logic issues rather than a player.
+- [`AddMember`][osrlib.crawl.commands.AddMember] adds a new member at the back, and
+  [`RemoveMember`][osrlib.crawl.commands.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. No command removes a member. The
-rules that count party members skip the dead: movement rate, combat ranks, traps, and food and
+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`][osrlib.crawl.party.Party.living_members].
 """
 
@@ -96,6 +97,8 @@ class Party(BaseModel):
 
     - To add a member during play, execute [`AddMember`][osrlib.crawl.commands.AddMember]. It
       assigns the new member's id and puts them at the back.
+    - To take a member out of play, execute
+      [`RemoveMember`][osrlib.crawl.commands.RemoveMember].
     - To change the order outside a fight, execute
       [`ReorderParty`][osrlib.crawl.commands.ReorderParty].
     - In a battle, a member who withdraws alone names the member to trade places with in
@@ -306,14 +309,17 @@ class Party(BaseModel):
         self.members = [by_id[character_id] for character_id in character_ids]
 
 
+def _stands(member: Character) -> bool:
+    """Whether a member stands, which means they are neither dead nor petrified."""
+    return not has_condition(member, Condition.DEAD) and not has_condition(member, Condition.PETRIFIED)
+
+
 def _anyone_standing(party: Party) -> bool:
     """Whether any member stands, which means they are neither dead nor petrified.
 
-    The session's `game_over` check and a battle's defeat check ask this. A statue still counts
-    among [`living_members`][osrlib.crawl.party.Party.living_members] for every other rule, so a
-    party turned wholly to stone has living members but nobody standing.
+    The session's `game_over` check and a battle's defeat check ask this, and
+    [`RemoveMember`][osrlib.crawl.commands.RemoveMember] refuses to take out the last member who
+    stands. A statue still counts among [`living_members`][osrlib.crawl.party.Party.living_members]
+    for every other rule, so a party turned wholly to stone has living members but nobody standing.
     """
-    return any(
-        not has_condition(member, Condition.DEAD) and not has_condition(member, Condition.PETRIFIED)
-        for member in party.members
-    )
+    return any(_stands(member) for member in party.members)

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/crawl/session.py

@@ -101,6 +101,7 @@ print(restored.view(Visibility.PLAYER) == view)
 # changes nothing, and spends no time until the last rejection check has passed. The referee and quest
 # command handlers are at the bottom of this module.
 
+import re
 from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Literal, Protocol
 
@@ -110,6 +111,7 @@ from osrlib.core.alignment import Alignment
 from osrlib.core.character import ADVANCEMENT_STREAM, Character
 from osrlib.core.classes import XpAwardResult, apply_xp, level_title
 from osrlib.core.clock import ROUNDS_PER_DAY, ROUNDS_PER_TURN, GameClock, TimeUnit
+from osrlib.core.combat import incapacitated
 from osrlib.core.effects import EFFECTS_STREAM, Condition, EffectsLedger
 from osrlib.core.events import (
     ConditionGainedEvent,
@@ -121,7 +123,7 @@ from osrlib.core.events import (
     SavingThrowRolledEvent,
     Visibility,
 )
-from osrlib.core.items import EquipmentCatalog, ItemInstance, MagicItemInstance
+from osrlib.core.items import EquipmentCatalog, Inventory, ItemInstance, MagicItemInstance
 from osrlib.core.monsters import MONSTER_SPAWN_STREAM, IdAllocator, MonsterCatalog, MonsterInstance, spawn_monster
 from osrlib.core.rng import RngStreams, StreamName
 from osrlib.core.ruleset import Ruleset
@@ -147,6 +149,7 @@ from osrlib.crawl.commands import (
     RecordNote,
     RemoveCoins,
     RemoveItem,
+    RemoveMember,
     RevealObjective,
     RollDice,
     SessionMode,
@@ -164,11 +167,13 @@ from osrlib.crawl.events import (
     FlagSetEvent,
     GameOverEvent,
     ItemAcquiredEvent,
+    ItemsGivenEvent,
     ItemsRemovedEvent,
     JournalEntryAddedEvent,
     LightEvent,
     LocationEnteredEvent,
     MemberAddedEvent,
+    MemberRemovedEvent,
     MonstersSpawnedEvent,
     NoteRecordedEvent,
     ObjectiveCompletedEvent,
@@ -179,7 +184,7 @@ from osrlib.crawl.events import (
     TriggerFiredEvent,
     XpAwardedEvent,
 )
-from osrlib.crawl.party import Party, _anyone_standing
+from osrlib.crawl.party import Party, _anyone_standing, _stands
 from osrlib.crawl.quests import ObjectiveSpec, QuestSpec
 from osrlib.data import load_equipment, load_magic_items, load_monsters
 from osrlib.errors import ContentValidationError
@@ -2290,6 +2295,113 @@ def _handle_add_member(session: GameSession, command: AddMember) -> tuple[list[R
     ]
 
 
+def _handle_remove_member(session: GameSession, command: RemoveMember) -> tuple[list[Rejection], list[Event]]:
+    try:
+        member = session.member(command.character_id)
+    except ValueError:
+        return [Rejection(code="session.command.unknown_member", params={"character": command.character_id})], []
+    recipient: Character | None = None
+    if command.give_to is not None:
+        try:
+            recipient = session.member(command.give_to)
+        except ValueError:
+            return [Rejection(code="session.command.unknown_member", params={"character": command.give_to})], []
+        if recipient is member:
+            return [Rejection(code="party.remove.same_member", params={"character": command.give_to})], []
+        if incapacitated(recipient):
+            return [Rejection(code="session.command.member_incapacitated", params={"character": command.give_to})], []
+    if not any(_stands(other) for other in session.party.members if other is not member):
+        return [Rejection(code="party.remove.last_standing", params={"character": command.character_id})], []
+    member_id = _member_id(member)
+    events: list[Event] = []
+    if recipient is not None:
+        events.extend(_hand_over_everything(session, member, recipient))
+    elif session.treasure_snapshot_cp is not None:
+        # The coins and valuables leave the party's total, so the baseline the return award
+        # measures against drops by the same amount, and the award doesn't change.
+        session.treasure_snapshot_cp -= member.inventory.purse.value_cp + sum(
+            valuable.value_gp * 100 for valuable in member.inventory.valuables
+        )
+    # Whatever the member still carries leaves with them, and so does every effect on them. An
+    # effect the member cast on another member targets that other member, so it stays.
+    session.ledger.effects = [effect for effect in session.ledger.effects if effect.target_ref != member_id]
+    session.death_records.pop(member_id, None)
+    session.deprivation.pop(member_id, None)
+    session.last_prepared_sleep.pop(member_id, None)
+    session.party.members = [other for other in session.party.members if other is not member]
+    _retire_member_id(session, member_id)
+    events.append(MemberRemovedEvent(character_id=member_id, name=member.name, given_to=command.give_to))
+    return [], events
+
+
+def _hand_over_everything(session: GameSession, giver: Character, recipient: Character) -> list[Event]:
+    """Move everything a leaving member carries to `recipient`, as a `GiveItems` of all of it would.
+
+    An equipped magic item releases its effects first, with events, and every item arrives
+    unequipped in the recipient's pack. Mundane gear joins the recipient's stacks. A revealed
+    curse held only its wearer, so a cursed item arrives no longer stuck, as *remove curse* would
+    leave it. Returns the releases and one `ItemsGivenEvent`, or no events when the member
+    carried nothing.
+    """
+    from osrlib.crawl import exploration
+
+    inventory = giver.inventory
+    events: list[Event] = []
+    item_ids: list[str] = []
+    for instance in inventory.all_instances():
+        if isinstance(instance, MagicItemInstance):
+            events.extend(exploration._release_instance_effects(session, instance))
+            instance.cursed_revealed = False
+            recipient.inventory.items.append(instance)
+            item_ids.append(instance.instance_id)
+        else:
+            exploration._grant_mundane(recipient, instance.template, instance.quantity)
+            item_ids.extend([instance.template.id] * instance.quantity)
+    for valuable in inventory.valuables:
+        recipient.inventory.valuables.append(valuable)
+        item_ids.append(valuable.instance_id)
+    purse = inventory.purse
+    moved_cp = purse.value_cp
+    moved_coins = purse.total_coins
+    recipient_purse = recipient.inventory.purse
+    for denomination in ("pp", "gp", "ep", "sp", "cp"):
+        setattr(recipient_purse, denomination, getattr(recipient_purse, denomination) + getattr(purse, denomination))
+    giver.inventory = Inventory()
+    if item_ids or moved_coins:
+        events.append(
+            ItemsGivenEvent(
+                character_id=_member_id(giver),
+                recipient_id=_member_id(recipient),
+                item_ids=tuple(item_ids),
+                coins_gp_value=moved_cp // 100,
+            )
+        )
+    return events
+
+
+def _retire_member_id(session: GameSession, member_id: str) -> None:
+    """Make sure the allocator never hands out a removed member's id.
+
+    The allocator counts up and never goes back, so moving its `character` count up to the
+    removed id's number retires that id and every one below it. That holds for an id the
+    allocator never issued, like one a member brought from an earlier session. The count lives
+    in the allocator, which a save contains, and a replay executes the removal again. An id
+    that isn't in the allocator's `character-NNNN` form is one the allocator can't produce, so
+    it needs nothing.
+    """
+    match = _ALLOCATED_CHARACTER_ID.fullmatch(member_id)
+    if match is None:
+        return
+    number = int(match.group(1))
+    if member_id != f"character-{number:04d}":
+        return
+    if number > session.allocator.counters.get("character", 0):
+        session.allocator.counters["character"] = number
+
+
+_ALLOCATED_CHARACTER_ID = re.compile(r"character-([0-9]+)")
+
+
 def _handle_award_xp(session: GameSession, command: AwardXP) -> tuple[list[Rejection], list[Event]]:
     try:
         member = session.member(command.character_id)
@@ -2714,4 +2826,5 @@ _REFEREE_HANDLERS = {
     RemoveItem: _handle_remove_item,
     RemoveCoins: _handle_remove_coins,
     AddMember: _handle_add_member,
+    RemoveMember: _handle_remove_member,
 }

{osrlib-2.1.0 → osrlib-2.2.0}/src/osrlib/messages.py

@@ -93,21 +93,27 @@ def _initiative(event: InitiativeRolledEvent) -> str:
 
 def _attack_hit(event: AttackRolledEvent) -> str:
     natural = " (natural 20)" if event.natural == 20 else ""
+    verb = "back-stabs" if event.back_stab else "hits"
     return (
-        f"{event.attacker_id} hits {event.defender_id} with {event.attack_name}: "
+        f"{event.attacker_id} {verb} {event.defender_id} with {event.attack_name}: "
         f"rolled {event.roll}{event.modifier:+d} = {event.total}, needing {event.required}{natural}."
     )
 
 
 def _attack_missed(event: AttackRolledEvent) -> str:
     natural = " (natural 1)" if event.natural == 1 else ""
+    attempt = f"a back-stab on {event.defender_id}" if event.back_stab else event.defender_id
     return (
-        f"{event.attacker_id} misses {event.defender_id} with {event.attack_name}: "
+        f"{event.attacker_id} misses {attempt} with {event.attack_name}: "
         f"rolled {event.roll}{event.modifier:+d} = {event.total}, needing {event.required}{natural}."
     )
 
 
 def _attack_auto(event: AttackRolledEvent) -> str:
+    if event.back_stab:
+        return (
+            f"{event.attacker_id} back-stabs the helpless {event.defender_id} with {event.attack_name}. No roll needed."
+        )
     return f"{event.attacker_id} strikes the helpless {event.defender_id} with {event.attack_name} — no roll needed."
 
 
@@ -450,6 +456,10 @@ _TEMPLATES: dict[str, Callable[[Any], str]] = {
     "session.member.added": lambda event: (
         f"{event.name}, a level {event.level} {event.class_id}, joins the party as {event.character_id}."
     ),
+    "session.member.removed": lambda event: (
+        f"{event.name} leaves the party"
+        + (f", and {event.given_to} takes their belongings." if event.given_to else ".")
+    ),
 }