osrlib 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osrlib
-Version: 2.1.0
+Version: 2.3.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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "osrlib"
-version = "2.1.0"
+version = "2.3.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.3.0}/src/osrlib/core/character.py

@@ -492,7 +492,7 @@ class Character(BaseModel):
         the +1 an ordinary shield gives. A worn item with an armour class bonus that is always
         active, like a ring of protection, adds to the bonus too.
         """
-        from osrlib.core.items import ArmourTemplate, MagicItemInstance, magic_item_template
+        from osrlib.core.items import ArmourTemplate, MagicItemInstance, _shield_ac_parts, magic_item_template
         from osrlib.data import load_equipment
 
         base = 10 if ascending else 9
@@ -509,21 +509,10 @@ class Character(BaseModel):
         elif worn is not None and isinstance(worn.template, ArmourTemplate) and worn.template.ac is not None:
             printed_ascending = worn.template.ac_ascending
             base = printed_ascending if ascending and printed_ascending is not None else worn.template.ac
-        bonus = 0
-        shield = self.inventory.shield
-        if isinstance(shield, MagicItemInstance):
-            template = magic_item_template(shield)
-            if template.ac_set is not None and template.ac_set_ascending is not None:
-                # The cursed shield's AC 9 [10] sets the wearer's base outright.
-                base = template.ac_set_ascending if ascending else template.ac_set
-            else:
-                mundane_shield = load_equipment().get("shield")
-                mundane_bonus = (getattr(mundane_shield, "ac_bonus", None) or 0) if mundane_shield else 0
-                bonus += mundane_bonus + template.ac_bonus
-        elif (
-            shield is not None and isinstance(shield.template, ArmourTemplate) and shield.template.ac_bonus is not None
-        ):
-            bonus += shield.template.ac_bonus
+        # The cursed shield's AC 9 [10] sets the wearer's base outright.
+        shield_base, bonus = _shield_ac_parts(self.inventory.shield, ascending=ascending)
+        if shield_base is not None:
+            base = shield_base
         for ring in self.inventory.rings:
             template = magic_item_template(ring)
             if template.always_active:

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

@@ -172,6 +172,7 @@ from osrlib.core.items import (
     MissileRanges,
     WeaponQuality,
     WeaponTemplate,
+    _shield_ac_parts,
     equipped_item_modifiers,
     magic_item_template,
 )
@@ -379,20 +380,29 @@ class AttackContext(BaseModel):
     behind_target: bool = False
     """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.
+    The defender's shield doesn't count, as the OSE SRD's "AC bonuses from shields are
+    negated" says. The attack is made against the armour class the defender would have
+    without the shield, so a magic shield loses its enchantment along with the +1 that every
+    shield gives. A cursed shield that makes the defender's armour class worse still counts,
+    because the rule takes away a shield's bonus and not its penalty. With `target_unaware`,
+    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.
     """
 
     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
     """Whether the defender is retreating.
 
-    The attacker gets +2 to hit, and the defender's shield doesn't count. A
+    The attacker gets +2 to hit, and the defender's shield doesn't count, as it doesn't with
+    `behind_target`. The attack is made against the armour class the defender would have
+    without the shield, a magic shield's enchantment included, but never a better one. A
     [`GameSession`][osrlib.crawl.session.GameSession] sets it for you in two cases:
 
     - On an attack against a monster group that's fleeing.
@@ -1353,12 +1363,12 @@ def _defender_descending_ac(defender: Any, context: AttackContext, *, missile: b
     ac = getattr(defender, "armour_class", None)
     if ac is None:
         return None
-    # Shield AC is ignored against a retreating defender and attacks from behind.
+    # A retreating defender, or one attacked from behind, loses the shield's bonus, a magic
+    # shield's enchantment included. A cursed shield's penalty has no bonus to lose, so it stays.
     if context.defender_retreating or context.behind_target:
         inventory = getattr(defender, "inventory", None)
-        shield = getattr(inventory, "shield", None) if inventory is not None else None
-        if shield is not None and shield.template.ac_bonus is not None:
-            ac += shield.template.ac_bonus
+        _, shield_bonus = _shield_ac_parts(getattr(inventory, "shield", None), ascending=False)
+        ac += max(shield_bonus, 0)
     if context.attacker_large:
         params = _class_ability_params(defender, "defensive_bonus")
         if params is not None:
@@ -1399,7 +1409,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.
@@ -1408,7 +1419,8 @@ def attack_roll(
     - The context's `situational_modifier`.
 
     The function adjusts the defender's armour class too. The defender's shield doesn't
-    count against an attack from behind, or while the defender retreats. The context's
+    count against an attack from behind, or while the defender retreats, and a magic
+    shield's enchantment doesn't count either. The context's
     `defender_ally_ac_bonus`, an armour class bonus that an ally gives the defender, does
     count.
 
@@ -1478,12 +1490,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 +1513,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 +1562,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.3.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.
@@ -1129,7 +1139,7 @@ class SpellDisruptedEvent(Event):
 
 
 class DeclarationFizzledEvent(Event):
-    """A declared wand, staff, or rod use, or a declared turning, failed before it took effect.
+    """A declared wand, staff, or rod use, a declared turning, or a declared melee attack failed before it took effect.
 
     A [`GameSession`][osrlib.crawl.session.GameSession] reports it during a battle round. At the start of each
     round, every party member declares an action in a
@@ -1140,36 +1150,53 @@ class DeclarationFizzledEvent(Event):
     caused the failure. For example, the group a staff of striking was aimed at moved out of melee reach, or the
     group a wand was aimed at left the battle.
 
-    The event's `actor_id` is the member who declared the action, `item_id` is the device, and `reason` is the
-    rejection code of the check that failed.
+    A melee attack fizzles when the party's melee step comes and the attack has nothing left to strike, or the
+    member stands in the wrong place. The session judges a melee attack before the round starts, as if every move the
+    round declares had happened. When the attack comes up, it resolves only if its group still has a living monster
+    the member can see to strike, and the member stands in the group's front rank within 5' of it. Something earlier
+    in the round can change either. For example, the party's missiles or spells kill every monster in the group, the
+    monsters win initiative and the group runs before the member's `close`, or a member the session expected to step
+    back can no longer move. Then the attack fizzles with the code `battle.melee.fizzled`. A group that has started to
+    flee is an exception to the position check: a member who stood within 5' of it when the round was accepted still
+    gets the attack, if the group has a monster left to strike and hasn't run out of the battle.
+
+    The event's `actor_id` is the member who declared the action, `item_id` is the device, `group_id` is the group a
+    melee attack was aimed at, and `reason` is the rejection code of the check that failed.
 
     A fizzled declaration spends nothing. The device wasn't used, so it keeps its charge and isn't identified. Tell
-    the player the action failed, and that the device still has its charge. When a cast or a scroll read fizzles,
+    the player the action failed, and that the device still has its charge. A fizzled melee attack makes no attack
+    roll, so tell the player why the member didn't swing. When a cast or a scroll read fizzles,
     the session reports a [`SpellDisruptedEvent`][osrlib.core.events.SpellDisruptedEvent] instead, because the
     spell is lost.
     """
 
-    allowed_codes: ClassVar[frozenset[str]] = frozenset({"magic.device.fizzled", "magic.turning.fizzled"})
-    """The two codes: `magic.device.fizzled` for a wand, staff, or rod use, and `magic.turning.fizzled` for a
-    turning."""
+    allowed_codes: ClassVar[frozenset[str]] = frozenset(
+        {"magic.device.fizzled", "magic.turning.fizzled", "battle.melee.fizzled"}
+    )
+    """The three codes: `magic.device.fizzled` for a wand, staff, or rod use, `magic.turning.fizzled` for a
+    turning, and `battle.melee.fizzled` for a melee attack."""
 
     event_type: Literal["declaration_fizzled"] = "declaration_fizzled"
     """The fixed string that identifies this event class in a serialized event."""
 
     code: str
-    """Which declaration fizzled: `magic.device.fizzled` or `magic.turning.fizzled`."""
+    """Which declaration fizzled: `magic.device.fizzled`, `magic.turning.fizzled`, or `battle.melee.fizzled`."""
 
     visibility: Visibility = Visibility.PLAYER
     """Player visibility: everyone sees the action fail."""
 
     actor_id: str
-    """The entity id of the member who declared the device use or the turning."""
+    """The entity id of the member who declared the device use, the turning, or the melee attack."""
 
     item_id: str | None = None
     """On a `magic.device.fizzled` event, the device's instance id, as the declaration's `item_id` gave it.
 
     The player already used this id, so it reveals nothing about a device that isn't identified. It's `None` on a
-    `magic.turning.fizzled` event."""
+    `magic.turning.fizzled` or a `battle.melee.fizzled` event."""
+
+    group_id: str | None = None
+    """On a `battle.melee.fizzled` event, the id of the group the melee attack was aimed at, as the declaration's
+    `target_group_id` gave it. It's `None` on the other codes."""
 
     reason: str
     """Why the declaration fizzled: the code of the first check that failed when the session checked it again.
@@ -1177,9 +1204,17 @@ class DeclarationFizzledEvent(Event):
     Any check the declaration passed at the start of the round can fail, so read the code and don't assume a
     cause. Some codes you may see:
 
-    - `combat.attack.out_of_reach`: the group a staff of striking was aimed at moved out of reach.
+    - `combat.attack.out_of_reach`: the group a staff of striking was aimed at moved out of reach, or the member
+      who declared a melee attack is farther than 5' from its group when the attack comes up. A melee attack gets
+      it too when its group ran out of the battle, wherever the member stood.
+    - `battle.declaration.not_in_front_rank`: the member who declared a melee attack is within 5' of its group
+      but not in its front rank when the attack comes up. A melee attack gets this code only when the member is
+      within 5', and `combat.attack.out_of_reach` otherwise.
     - `battle.declaration.unknown_group`: the group a wand was aimed at left the battle.
-    - `battle.declaration.no_target`: no living monster is left in the battle for a turning.
+    - `battle.declaration.no_target`: no living monster is left in the battle for a turning, or no living monster
+      the member can see is left in the group a melee attack was aimed at, for example because the party's missiles
+      or spells killed them earlier in the round. A melee attack gets this code wherever the member stands, whether
+      or not the member closed, because the session checks for a target before it checks the member's position.
 
     Match on it as you match on the code of a [`Rejection`][osrlib.core.validation.Rejection].
     [The rejection code reference][rejection-codes] explains each code.

{osrlib-2.1.0 → osrlib-2.3.0}/src/osrlib/core/items.py

@@ -2254,6 +2254,28 @@ def magic_item_template(instance: MagicItemInstance) -> MagicItemTemplate:
     return load_magic_items().get(instance.template_id)
 
 
+def _shield_ac_parts(shield: AnyInstance | None, *, ascending: bool) -> tuple[int | None, int]:
+    """Return the armour class a shield sets, or None, and the bonus the shield adds to armour class.
+
+    A mundane shield adds its +1. A magic shield adds its enchantment on top of the +1 an ordinary
+    shield gives, so a cursed shield's negative enchantment can make the sum a penalty. The cursed
+    shield that prints AC 9 [10] sets the wearer's armour class outright and adds nothing.
+    `Character._armour_parts` and the attack roll both read a shield here, so they agree on what it
+    gives.
+    """
+    from osrlib.data import load_equipment
+
+    if isinstance(shield, MagicItemInstance):
+        template = magic_item_template(shield)
+        if template.ac_set is not None and template.ac_set_ascending is not None:
+            return (template.ac_set_ascending if ascending else template.ac_set), 0
+        mundane = load_equipment().get("shield")
+        return None, (getattr(mundane, "ac_bonus", None) or 0) + template.ac_bonus
+    if shield is not None and isinstance(shield.template, ArmourTemplate) and shield.template.ac_bonus is not None:
+        return None, shield.template.ac_bonus
+    return None, 0
+
+
 def equipped_item_modifiers(inventory: Inventory) -> list[ModifierSpec]:
     """Return the stat modifiers a character's equipped magic items grant.