dnd5e-engine 0.4.0__tar.gz → 0.5.0__tar.gz

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0]
+
+Lockstep release with `dnd5e-srd-data` 0.5.0 and `nat20-bridge` 0.5.0.
+
+Removes the legacy (Gen 1) rules surface deprecated in 0.4.0. The engine now
+ships exactly one, seedable, documented rules implementation
+(`orchestrator` + `activities/`). See `docs/migration/v0.4-to-v0.5.md`.
+
+### Removed
+
+- Modules `dispatch`, `event_dicts`, `types.dice`, `types.intent`, and
+  `rules.{combat, combat_data, combat_helpers, equipment, gambits, resolution,
+  spells}` (plus the private `rules._parsing` / `rules._class_meta`).
+- `dnd5e_engine.ActionType`, `CombatNPC`, and the lazy
+  `dnd5e_engine.types.{ActionType, CombatOutcome, DiceOutcome, CombatNPC}`
+  re-exports; the 0.4.0 `DeathSaveState` / `BehaviorProfile` re-export shims.
+- The cross-generation parity test; its Gen 2 assertions live on in
+  `tests/test_attack_classification.py`.
+
 ## [0.4.0]
 
 Lockstep release with `dnd5e-srd-data` 0.4.0 and `nat20-bridge` 0.4.0.

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dnd5e-engine
-Version: 0.4.0
+Version: 0.5.0
 Summary: Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O.
 Author: Tapestria contributors
 License: MIT License

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.4.0"
+version = "0.5.0"
 description = "Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -88,10 +88,8 @@ max-complexity = 23
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 filterwarnings = [
-    # Any DeprecationWarning the engine itself raises is a bug — except the
-    # 0.4.0 legacy-surface deprecations, which the suite exercises on purpose.
+    # Any DeprecationWarning the engine itself raises is a bug.
     "error::DeprecationWarning:dnd5e_engine",
-    "ignore:.*legacy \\(Gen 1\\) surface.*:DeprecationWarning",
 ]
 
 [tool.coverage.run]

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/src/dnd5e_engine/__init__.py

@@ -82,7 +82,6 @@ from dnd5e_engine.types.effects import (
 
 __all__ = [
     "AbilityScores",
-    "ActionType",
     "ActiveEffect",
     "ActiveEffectChange",
     "ActiveEffectDuration",
@@ -129,25 +128,3 @@ __all__ = [
     "start_combat",
     "submit_player_intent",
 ]
-
-_GEN1_LAZY = {"ActionType": ("dnd5e_engine.types.intent", "ActionType")}
-
-
-def __getattr__(name: str) -> object:
-    # PEP 562 — keep the 0.3.x names resolvable without importing the
-    # deprecated modules eagerly (which would warn on every ``import dnd5e_engine``).
-    if name in _GEN1_LAZY:
-        import importlib
-        import warnings
-
-        module, attr = _GEN1_LAZY[name]
-        warnings.warn(
-            f"dnd5e_engine.{name} belongs to the legacy (Gen 1) surface — a host-side "
-            f"shape, not an engine type — and will be removed in dnd5e-engine 0.5.0. "
-            f"Import it from {module} (also deprecated) or copy it into your host; "
-            f"see docs/migration/v0.3-to-v0.4.md.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return getattr(importlib.import_module(module), attr)
-    raise AttributeError(f"module 'dnd5e_engine' has no attribute {name!r}")

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/src/dnd5e_engine/specs.py

@@ -170,7 +170,7 @@ class EncounterMemberSpec(BaseModel):
     # Person targets humanoids; Sleep autopasses undead/elves; etc.).
     creature_type: str | None = None
     # SRD §Damage Resistance / §Damage Immunity — per-monster type lists,
-    # populated from MonsterTemplate (via CombatMonster / CombatNPC). Empty
+    # populated from the host's monster template record. Empty
     # by default for fixtures that don't specify.
     damage_resistances: list[str] = Field(default_factory=list)
     damage_immunities: list[str] = Field(default_factory=list)

dnd5e_engine-0.5.0/src/dnd5e_engine/types/__init__.py

@@ -0,0 +1,18 @@
+"""dnd5e-engine type surface — host-agnostic Pydantic + Literal types."""
+
+from dnd5e_engine.types.combat import Combatant
+from dnd5e_engine.types.conditions import ActiveCondition, ConditionScope
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+    ActiveEffectDuration,
+)
+
+__all__ = [
+    "ActiveCondition",
+    "ActiveEffect",
+    "ActiveEffectChange",
+    "ActiveEffectDuration",
+    "Combatant",
+    "ConditionScope",
+]

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/src/dnd5e_engine/types/combat.py

@@ -1,4 +1,4 @@
-"""Combat participant types — ``Combatant`` + ``CombatNPC``.
+"""Combat participant types — ``Combatant`` and ``BehaviorProfile``.
 
 Host-agnostic value types: stdlib + pydantic + the engine's own
 ``ActiveCondition``. ``Combatant`` is the engine's per-creature runtime combat
@@ -24,35 +24,6 @@ class BehaviorProfile(StrEnum):
     DEFENSIVE = "DEFENSIVE"
 
 
-class CombatNPC(BaseModel):
-    """Ephemeral sidecar record for an NPC in combat. Host-scoped;
-    cleared at end of combat. Owns template-derived combat stats that don't
-    fit on the narrow Combatant: saves, resistances, immunities, ability
-    scores, behavior_profile. Symmetric to CombatMonster for non-Character
-    entities."""
-
-    npc_id: str  # persistent NPC node ID (npc:hex12)
-    template_id: str  # MonsterTemplate node ID used at materialization
-    name: str
-    hp_current: int
-    hp_max: int
-    ac: int
-    attack_bonus: int
-    damage_dice: str
-    damage_type: str
-    has_ranged_attack: bool = False
-    dexterity: int = 10
-    strength: int = 10
-    constitution: int = 10
-    wisdom: int = 10
-    intelligence: int = 10
-    charisma: int = 10
-    behavior_profile: str = "AGGRESSIVE"
-    damage_resistances: list[str] = Field(default_factory=list)
-    damage_immunities: list[str] = Field(default_factory=list)
-    is_alive: bool = True
-
-
 class Combatant(BaseModel):
     entity_id: str
     entity_type: str  # "Character" | "Monster" | "NPC"
@@ -110,7 +81,7 @@ class Combatant(BaseModel):
     # application path (``activities/effects.py::apply_activity_effects``)
     # suppresses a ``ConditionApplied`` whose condition is in this list
     # . Empty by default. NOTE: distinct from the dead, host-supplied
-    # ``dispatch.py::DispatchContext.condition_immunities`` legacy surface.
+    # legacy dispatch surface's ``condition_immunities`` (removed in 0.5.0).
     condition_immunities: list[str] = Field(default_factory=list)
     # SRD §Senses — special senses in feet (darkvision/blindsight/tremorsense/
     # truesight). Projected from PC species + always-on feature passive_effects
@@ -224,6 +195,5 @@ class Combatant(BaseModel):
 
 __all__ = [
     "BehaviorProfile",
-    "CombatNPC",
     "Combatant",
 ]

dnd5e_engine-0.5.0/tests/activities/test_save_dc_and_damage_exprs.py

@@ -0,0 +1,129 @@
+"""Direct pins on ``activities/save.py::_resolve_dc`` and the damage-expression
+builders in ``activities/dice.py`` / ``activities/formula.py``.
+
+The end-to-end scenarios reach these only through the corpus' common shapes
+(spellcasting DC, automatic ``{n}d{d}`` formulas); the flat-DC, custom-formula
+and scaling-token branches are pinned here.
+"""
+
+from __future__ import annotations
+
+import random
+
+import pytest
+from dnd5e_srd_data.loader import BundledAssetLoader
+from dnd5e_srd_data.schema.common import (
+    DamageCustomBlock,
+    DamagePart,
+    DamagePartBlock,
+    DamageScalingBlock,
+    SaveActivity,
+)
+
+from dnd5e_engine.activities.context import ActivityResolutionContext
+from dnd5e_engine.activities.dice import damage_part_to_expr
+from dnd5e_engine.activities.formula import resolve_damage_block
+from dnd5e_engine.activities.save import _resolve_dc
+from dnd5e_engine.types.combat import Combatant
+
+
+def _ctx(**overrides: object) -> ActivityResolutionContext:
+    kwargs: dict[str, object] = dict(
+        rng=random.Random(1),
+        caster=Combatant(
+            entity_id="char:wiz",
+            entity_type="Character",
+            name="Wiz",
+            initiative=10,
+            hp_current=10,
+            hp_max=10,
+        ),
+        targets=[],
+        event_emitter=lambda ev: None,
+        caster_abilities={"str": 10, "dex": 10, "con": 10, "int": 16, "wis": 10, "cha": 10},
+        caster_proficiency_bonus=2,
+        spellcasting_ability="int",
+    )
+    kwargs.update(overrides)
+    return ActivityResolutionContext(**kwargs)  # type: ignore[arg-type]
+
+
+@pytest.fixture(scope="module")
+def fireball_save() -> SaveActivity:
+    spell = BundledAssetLoader().get_spell("fireball")
+    assert spell is not None
+    activity = next(a for a in spell.activities if a.kind == "save")
+    assert isinstance(activity, SaveActivity)
+    return activity
+
+
+def _with_dc(activity: SaveActivity, calculation: str, formula: str = "") -> SaveActivity:
+    dc = activity.save.dc.model_copy(update={"calculation": calculation, "formula": formula})
+    return activity.model_copy(update={"save": activity.save.model_copy(update={"dc": dc})})
+
+
+# ── _resolve_dc ──────────────────────────────────────────────────────────────
+
+
+def test_spellcasting_dc_is_8_plus_prof_plus_mod(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(fireball_save, _ctx()) == 8 + 2 + 3
+
+
+def test_spellcasting_dc_without_a_casting_ability_is_loud(fireball_save: SaveActivity) -> None:
+    with pytest.raises(ValueError, match="spellcasting ability"):
+        _resolve_dc(fireball_save, _ctx(spellcasting_ability=None))
+
+
+def test_flat_dc_resolves_the_formula(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(_with_dc(fireball_save, "flat", "13"), _ctx()) == 13
+
+
+def test_flat_dc_resolves_roll_data_tokens(fireball_save: SaveActivity) -> None:
+    # @prof folds to the caster's proficiency bonus before evaluation.
+    assert _resolve_dc(_with_dc(fireball_save, "flat", "10 + @prof"), _ctx()) == 12
+
+
+def test_unknown_dc_calculation_is_loud(fireball_save: SaveActivity) -> None:
+    with pytest.raises(ValueError, match="not resolvable"):
+        _resolve_dc(_with_dc(fireball_save, "mystery"), _ctx())
+
+
+def test_save_dc_override_bypasses_the_calculation(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(_with_dc(fireball_save, "mystery"), _ctx(save_dc_override=18)) == 18
+
+
+# ── damage_part_to_expr ──────────────────────────────────────────────────────
+
+
+def test_weapon_damage_part_passes_its_dice_string_through() -> None:
+    assert damage_part_to_expr(DamagePart(dice="2d6+3", damage_type="slashing")) == "2d6+3"
+
+
+def test_activity_block_builds_the_automatic_formula() -> None:
+    assert damage_part_to_expr(DamagePartBlock(number=2, denomination=6, bonus="3")) == "2d6+3"
+
+
+def test_activity_block_with_only_a_bonus_is_the_bare_bonus() -> None:
+    assert damage_part_to_expr(DamagePartBlock(bonus="5")) == "5"
+
+
+def test_activity_block_custom_formula_wins_when_enabled() -> None:
+    block = DamagePartBlock(
+        number=2, denomination=6, custom=DamageCustomBlock(enabled=True, formula="1d4")
+    )
+    assert damage_part_to_expr(block) == "1d4"
+
+
+# ── resolve_damage_block ─────────────────────────────────────────────────────
+
+
+def test_scaling_formula_tokens_are_resolved_off_the_context() -> None:
+    block = DamagePartBlock(number=1, denomination=8, scaling=DamageScalingBlock(formula="@prof"))
+    resolved = resolve_damage_block(block, _ctx(), ability="int")
+    assert resolved.scaling.formula == "2"
+    assert resolved.number == 1  # untouched fields survive the copy
+
+
+def test_block_without_tokens_is_returned_unchanged() -> None:
+    block = DamagePartBlock(number=1, denomination=8, bonus="2")
+    assert resolve_damage_block(block, _ctx(), ability="int") is block

dnd5e_engine-0.5.0/tests/test_attack_classification.py

@@ -0,0 +1,84 @@
+"""Pin the SRD hit / crit / miss classification of the attack resolver.
+
+Carried over from the (now retired) cross-generation parity test: these are
+the rules whose drift between the two former implementations motivated the
+0.5.0 consolidation, so they stay pinned on the surviving path.
+"""
+
+from __future__ import annotations
+
+import random
+
+import pytest
+from dnd5e_srd_data.loader import BundledAssetLoader
+from dnd5e_srd_data.schema.common import AttackActivity
+
+from dnd5e_engine.activities.attack import _resolve_hit_outcome, _roll_natural_d20
+from dnd5e_engine.activities.context import ActivityResolutionContext
+from dnd5e_engine.types.combat import Combatant
+
+
+@pytest.fixture(scope="module")
+def attack() -> AttackActivity:
+    longsword = BundledAssetLoader().get_weapon("longsword")
+    assert longsword is not None
+    activity = next(a for a in longsword.activities if a.kind == "attack")
+    assert isinstance(activity, AttackActivity)
+    return activity
+
+
+def _ctx(seed: int) -> ActivityResolutionContext:
+    hero = Combatant(
+        entity_id="char:hero",
+        entity_type="Character",
+        name="Hero",
+        initiative=10,
+        hp_current=10,
+        hp_max=10,
+    )
+    return ActivityResolutionContext(
+        rng=random.Random(seed),
+        caster=hero,
+        targets=[],
+        event_emitter=lambda ev: None,
+        caster_abilities={"str": 10, "dex": 10, "con": 10, "int": 10, "wis": 10, "cha": 10},
+    )
+
+
+def test_natural_one_always_misses_even_with_a_huge_bonus(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(1, 1 + 50, 10, attack) == (False, False)
+
+
+def test_natural_twenty_always_crits_even_against_impossible_ac(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(20, 20, 99, attack) == (True, True)
+
+
+def test_meeting_the_ac_exactly_is_a_hit(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(10, 15, 15, attack) == (False, True)
+
+
+def test_falling_one_short_of_the_ac_is_a_miss(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(10, 14, 15, attack) == (False, False)
+
+
+@pytest.mark.parametrize("seed", range(32))
+def test_advantage_keeps_the_higher_and_disadvantage_the_lower_die(seed: int) -> None:
+    rng = random.Random(seed)
+    a, b = rng.randint(1, 20), rng.randint(1, 20)
+    assert _roll_natural_d20(_ctx(seed), "advantage") == max(a, b)
+    assert _roll_natural_d20(_ctx(seed), "disadvantage") == min(a, b)
+    assert _roll_natural_d20(_ctx(seed), "normal") == a
+
+
+def test_disadvantage_does_not_crit_on_the_discarded_die(attack: AttackActivity) -> None:
+    # Find a seed whose two dice are (20, x<20): the kept die under disadvantage
+    # must not be the discarded 20.
+    for seed in range(500):
+        rng = random.Random(seed)
+        a, b = rng.randint(1, 20), rng.randint(1, 20)
+        if 20 in (a, b) and min(a, b) < 20:
+            natural = _roll_natural_d20(_ctx(seed), "disadvantage")
+            assert natural == min(a, b)
+            assert _resolve_hit_outcome(natural, natural, 99, attack)[0] is False
+            return
+    pytest.fail("no seed with a discarded 20 in 500 tries")

dnd5e_engine-0.5.0/tests/test_combat_bucket_keys.py

@@ -0,0 +1,61 @@
+"""Regression — combat resolvers use Foundry-shaped bucket keys (Phase 6).
+
+Codex review of Phase 6 caught that ``rules/combat.py`` was passing legacy
+bucket strings (``"saving_throw"``, ``"damage"``, ``"attack_roll"``, ``"ac"``)
+into ``apply_changes_to_check``. The seed templates emit Foundry-shaped keys
+(``save.bonus``, ``damage.bonus``, ``attack.roll.bonus``, ``ac.bonus``); the
+helper does exact key matching, so the resolvers were silently no-op-ing
+every effect. These tests lock the alignment.
+"""
+
+from __future__ import annotations
+
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+    ActiveEffectDuration,
+)
+
+
+def _bless(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped Bless: +1d4 on attack rolls and saves (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:bless",
+        name="Bless",
+        origin="cast:bless:1",
+        target_id=target_id,
+        duration=ActiveEffectDuration(rounds=10),
+        changes=[
+            ActiveEffectChange(key="attack.roll.bonus", mode="add", value="1d4"),
+            ActiveEffectChange(key="save.bonus", mode="add", value="1d4"),
+        ],
+        flags={"concentration": True},
+    )
+
+
+def _cloak(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped Cloak of Protection: +1 AC and +1 saves (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:cloak_of_protection",
+        name="Cloak of Protection",
+        origin="item:cloak_of_protection:1",
+        target_id=target_id,
+        changes=[
+            ActiveEffectChange(key="ac.bonus", mode="add", value=1),
+            ActiveEffectChange(key="save.bonus", mode="add", value=1),
+        ],
+    )
+
+
+def _plus_one_sword(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped +1 Weapon: +1 attack and +1 damage (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:weapon_plus_1",
+        name="+1 Weapon",
+        origin="item:weapon_plus_1:1",
+        target_id=target_id,
+        changes=[
+            ActiveEffectChange(key="attack.roll.bonus", mode="add", value=1),
+            ActiveEffectChange(key="damage.bonus", mode="add", value=1),
+        ],
+    )

dnd5e_engine-0.5.0/tests/test_combat_flag_advantage.py

@@ -0,0 +1,25 @@
+"""Regression — combat resolvers honor flag-based advantage / disadvantage.
+
+Codex Phase 6 review iter-12 P2: combat.py's saving_throw and
+resolve_player_attack didn't read flag-based advantage / disadvantage
+from active_effects, so Restrained / Guidance-style / Faerie Fire /
+Invisible effects didn't shift the d20 mechanic in combat. Now both
+mirror the iter-10/11 resolve_check fix.
+"""
+
+from __future__ import annotations
+
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+)
+
+
+def _flag_effect(key: str, target_id: str = "char:hero") -> ActiveEffect:
+    return ActiveEffect(
+        id=f"effect:test_{key}",
+        name=f"test_{key}",
+        origin=f"cast:test:{key}",
+        target_id=target_id,
+        changes=[ActiveEffectChange(key=key, mode="override", value=True)],
+    )

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/tests/test_gen2_has_no_gen1_imports.py

@@ -7,6 +7,7 @@ the supported ones.
 from __future__ import annotations
 
 import ast
+import importlib.util
 import subprocess
 import sys
 
@@ -50,3 +51,8 @@ def test_gen2_entry_points_load_no_gen1_module() -> None:
     loaded = _loaded_modules()
     leaked = [m for m in loaded if m in GEN1]
     assert leaked == [], leaked
+
+
+def test_gen1_modules_no_longer_exist() -> None:
+    present = [m for m in GEN1 if importlib.util.find_spec(m) is not None]
+    assert present == [], present

{dnd5e_engine-0.4.0 → dnd5e_engine-0.5.0}/tests/test_public_api_surface.py

@@ -5,7 +5,6 @@ import dnd5e_engine
 
 TOP_LEVEL = {
     "AbilityScores",
-    "ActionType",
     "ActiveEffect",
     "ActiveEffectChange",
     "ActiveEffectDuration",
@@ -54,21 +53,12 @@ TOP_LEVEL = {
 }
 
 PUBLIC_MODULES = [
-    "dnd5e_engine.rules.combat",
     "dnd5e_engine.rules.conditions",
     "dnd5e_engine.rules.dice",
-    "dnd5e_engine.rules.equipment",
-    "dnd5e_engine.rules.gambits",
-    "dnd5e_engine.rules.resolution",
     "dnd5e_engine.rules.skills",
-    "dnd5e_engine.rules.spells",
-    "dnd5e_engine.rules.combat_data",
-    "dnd5e_engine.rules.combat_helpers",
     "dnd5e_engine.events",
-    "dnd5e_engine.event_dicts",
     "dnd5e_engine.death_saves",
     "dnd5e_engine.outcome",
-    "dnd5e_engine.dispatch",
     "dnd5e_engine.specs",
     "dnd5e_engine.spatial",
     "dnd5e_engine.lib_loader",
@@ -77,10 +67,8 @@ PUBLIC_MODULES = [
     "dnd5e_engine.build_spec",
     "dnd5e_engine.build_party",
     "dnd5e_engine.results",
-    "dnd5e_engine.types.intent",
     "dnd5e_engine.types.combat",
     "dnd5e_engine.types.conditions",
-    "dnd5e_engine.types.dice",
     "dnd5e_engine.types.effects",
     "dnd5e_engine.testing",
 ]