osrlib 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osrlib
-Version: 2.2.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.2.0 → osrlib-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "osrlib"
-version = "2.2.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.2.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.2.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,8 +380,12 @@ 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, and the attack's
+    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.
     """
 
@@ -395,7 +400,9 @@ class AttackContext(BaseModel):
     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.
@@ -1356,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:
@@ -1412,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.
 

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

@@ -1139,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
@@ -1150,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.
@@ -1187,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.2.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.