dnd5e-engine 0.2.0__tar.gz → 0.3.1__tar.gz

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0]
+
+Lockstep release with `dnd5e-srd-data` 0.3.0 — the item charge lifecycle: gate
+→ spend → cast-delegate → upcast → recharge → observe. See
+`docs/migration/v0.2-to-v0.3.md` for the full, host-facing migration guide.
+The engine now depends on `dnd5e-srd-data>=0.3.0` (the charge-gate and
+cast-delegation paths read the new `Item.uses` / `Spell.foundry_uuid` schema).
+
+### Added
+
+- **Item charges** — `use_item` now validates and spends `consumption.targets[type=itemUses]`
+  costs against the item's `uses.max` pool, tracked in the `custom_counters` sidecar under
+  `item_use:<slug>` (`{"spent": n}`). Exhausted pools reject with
+  `CastFailed(reason="no_charges_remaining")` before the action budget is touched. Items
+  without a pool are unaffected. `CastFailedReason` also gains `invalid_charge_spend`, emitted
+  when a `charges_to_spend` request violates the activity's `consumption.scaling` (see
+  "Charge upcasting" below).
+- **Item recharge** — `dnd5e_engine.rest.recover_item_uses` (+ `ITEM_USE_COUNTER_PREFIX`,
+  submodule-only export): pure recharge over `item_use:` pools. The engine's own
+  `rest.RecoveryPeriod` gains `"dawn"`/`"day"`/`"dusk"` (previously just `"sr"`/`"lr"`;
+  the data package's `RecoveryRule` already knew `"day"` — this widens the engine's
+  narrower rest-period literal to match); formula recovery now rolls dice ("1d6 + 1")
+  through an optional `rng` (also available on `recover_feature_uses`).
+- **Cast delegation** — a used item's `CastActivity` now resolves its referenced spell
+  (uuid→Spell via `dnd5e-srd-data`'s `get_spell_by_uuid`) on the PC-intent path, honoring
+  the item's flat DC / attack / level overrides. `cast_spell_unresolved` now signals a
+  genuinely missing uuid, not missing plumbing.
+- **Charge upcasting** — `PlayerIntent.charges_to_spend` casts at
+  `base level + extra charges`, validated against `consumption.scaling`
+  (`invalid_charge_spend` on violation). New `ActivityResolutionContext.cast_level_override`.
+- **Charge read path** — `LiveCombatView.custom_counters_by_entity` (three-level snapshot
+  copy): hosts mirror `item_use:` / `feature_use:` pools per turn the same way they mirror
+  `spell_slots_by_entity`.
+
 ## [0.2.0]
 
 Lockstep release with `dnd5e-srd-data` 0.2.0 — the outcome of the gap-closing

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dnd5e-engine
-Version: 0.2.0
+Version: 0.3.1
 Summary: Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O.
 Author: Tapestria contributors
 License: MIT License
@@ -34,7 +34,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: d20>=1.1.2
-Requires-Dist: dnd5e-srd-data>=0.2.0
+Requires-Dist: dnd5e-srd-data>=0.3.0
 Requires-Dist: pydantic>=2.10.0
 Provides-Extra: dev
 Requires-Dist: bandit>=1.8.0; extra == 'dev'

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.2.0"
+version = "0.3.1"
 description = "Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -24,7 +24,9 @@ dependencies = [
     # lib_loader imports BundledAssetLoader at runtime; the typed-Activity
     # resolver reads the canonical corpus through it. The data lib's >=3.12
     # floor is why this package now also requires >=3.12 (see requires-python).
-    "dnd5e-srd-data>=0.2.0",
+    # Lockstep floor: the charge gate reads Item.uses / Spell.foundry_uuid,
+    # which srd-data carries from 0.3.0 on.
+    "dnd5e-srd-data>=0.3.0",
 ]
 
 [project.optional-dependencies]

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/__init__.py

@@ -13,7 +13,7 @@ Deferred for later phases:
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 
 from dnd5e_engine.build_party import build_party_member
 from dnd5e_engine.build_spec import (
@@ -24,6 +24,7 @@ from dnd5e_engine.build_spec import (
 )
 from dnd5e_engine.check import CheckKind, CheckResult, CheckSpec, resolve_check
 from dnd5e_engine.events import CombatEvent, IntentType
+from dnd5e_engine.lib_loader import configure_lib_loader
 from dnd5e_engine.orchestrator import (
     CombatHandle,
     LiveCombatView,
@@ -46,6 +47,7 @@ from dnd5e_engine.rest import (
     RecoveryPeriod,
     RestOutcome,
     recover_feature_uses,
+    recover_item_uses,
     resolve_long_rest,
     resolve_short_rest,
 )
@@ -100,6 +102,7 @@ __all__ = [
     "advance_monster_turn",
     "build_party_member",
     "cell_id",
+    "configure_lib_loader",
     "end_combat",
     "get_actor_active_effects",
     "get_live",
@@ -107,6 +110,7 @@ __all__ = [
     "narration_events",
     "parse_cell",
     "recover_feature_uses",
+    "recover_item_uses",
     "resolve_check",
     "resolve_long_rest",
     "resolve_short_rest",

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/activities/build_context.py

@@ -147,6 +147,7 @@ def build_activity_context(
     target_cover: dict[str, str] | None = None,
     scale_values: dict[str, int | str] | None = None,
     class_levels: dict[str, int] | None = None,
+    cast_level_override: int | None = None,
     is_feature_invocation: bool = False,
     active_effects: Sequence[ActiveEffect] = (),
     sneak_attack_spent: dict[str, bool] | None = None,
@@ -185,6 +186,14 @@ def build_activity_context(
     So for a feature invocation the override is omitted (``None``), letting the
     save resolver fall through to ``save.dc.calculation``. The spell / item
     path keeps the blanket override.
+
+    ``cast_level_override`` passes straight through to
+    :class:`ActivityResolutionContext` — a ``use_item`` charges_to_spend
+    upcast's forced delegated-cast level (orchestrator-computed off the
+    charge gate's own cost accounting). ``None`` (the default) leaves
+    ``resolve_cast`` (``activities/cast.py``) to fall back to the wrapper
+    activity's own/base spell level, unchanged from before this field
+    existed.
     """
     mod = _caster_mod(caster)
     if caster.entity_type == "Character":
@@ -346,4 +355,5 @@ def build_activity_context(
         spell_book=spell_book,
         scale_values=scale_values or {},
         class_levels=class_levels or {},
+        cast_level_override=cast_level_override,
     )

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/activities/cast.py

@@ -26,8 +26,15 @@ honored: 42 canonical cast activities (Dragon Orb DC 18, Circlet of Blasting +5,
 …) carry a FIXED save DC or attack bonus. The handler threads the fixed value
 into the child context (``save_dc_override`` / ``attack_bonus_override``); the
 delegated save/attack handler uses it verbatim instead of the wielder's stats.
-Both fields are set unconditionally so a non-override cast clears any inherited
-stale value (a grandchild never inherits a parent scroll's DC).
+A non-override cast still CLEARS the field for a NESTED cast (a grandchild
+never inherits a parent scroll's DC) — but a TOP-LEVEL item wrapper (nothing
+above it in ``ctx.parent_chain``) has no ``spellcasting_ability`` of its own,
+so clearing unconditionally would strip the blanket flat DC / attack bonus
+``build_activity_context`` computed for the item path, and the delegated
+save/attack handler would either raise (``save.py``, ``calculation ==
+"spellcasting"`` with no ability) or silently drop the ability-mod term
+(``attack.py``). A top-level wrapper without its own override therefore
+FALLS BACK to the inherited ``ctx`` value instead of clearing.
 """
 
 from __future__ import annotations
@@ -61,7 +68,12 @@ def resolve_cast(activity: CastActivity, ctx: ActivityResolutionContext) -> None
     #    A cantrip's base level is 0 (``0 <= 0 <= 9`` passes). An out-of-range
     #    cast (e.g. a scroll forged at level 10, or below the spell's base) is a
     #    LOUD no-op — never an absurd upcast (cure-wounds at level 10 → 20d8).
-    cast_level = activity.spell.level if activity.spell.level is not None else spell.level
+    if ctx.cast_level_override is not None:
+        cast_level = ctx.cast_level_override
+    elif activity.spell.level is not None:
+        cast_level = activity.spell.level
+    else:
+        cast_level = spell.level
     if not (spell.level <= cast_level <= 9):
         _LOGGER.warning(
             "cast_invalid_level uuid=%s cast_level=%s base_level=%s",
@@ -78,9 +90,13 @@ def resolve_cast(activity: CastActivity, ctx: ActivityResolutionContext) -> None
     #    A fixed item challenge (``spell.challenge.override``) threads a verbatim
     #    save DC / attack bonus into the child so the delegated save/attack handler
     #    uses the item's number, not the wielder's stats (Dragon Orb DC 18, Circlet
-    #    of Blasting +5). Both are set UNCONDITIONALLY: an override is honored for
-    #    THIS wrapper, and a non-override cast CLEARS any inherited stale value so a
-    #    grandchild never inherits a parent scroll's DC.
+    #    of Blasting +5). An override is honored for THIS wrapper. Absent an
+    #    override: a NESTED cast (``ctx.parent_chain`` non-empty — this wrapper is
+    #    itself inside another cast's delegation) CLEARS the field so a grandchild
+    #    never inherits a parent scroll's DC; a TOP-LEVEL wrapper (nothing above us
+    #    in the chain) has no ``spellcasting_ability`` to fall through to, so it
+    #    INHERITS ``ctx``'s value — the item-path blanket DC / attack bonus
+    #    ``build_activity_context`` already computed for it.
     from .resolver import resolve_activity  # function-local: breaks the resolver↔cast import cycle
 
     challenge = activity.spell.challenge
@@ -91,8 +107,21 @@ def resolve_cast(activity: CastActivity, ctx: ActivityResolutionContext) -> None
         base_spell_level=spell.level,
         concentration=spell.concentration,
         source_passive_effects=spell.passive_effects,
-        save_dc_override=(challenge.save if challenge.override else None),
-        attack_bonus_override=(challenge.attack if challenge.override else None),
+        save_dc_override=(
+            challenge.save
+            if challenge.override
+            else (ctx.save_dc_override if not ctx.parent_chain else None)
+        ),
+        attack_bonus_override=(
+            challenge.attack
+            if challenge.override
+            else (ctx.attack_bonus_override if not ctx.parent_chain else None)
+        ),
+        # M1: a nested cast must never inherit the item wrapper's forced cast
+        # level (``use_item`` charges_to_spend upcast) — only the wrapper's own
+        # ``CastActivity`` consumes it; the referenced spell's own activities
+        # cast at ``cast_level`` computed above, not the raw override again.
+        cast_level_override=None,
         parent_chain=(*ctx.parent_chain, uuid),
     )
     for child_activity in spell.activities:

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/activities/context.py

@@ -58,6 +58,11 @@ class ActivityResolutionContext:
     # (`spell.challenge.override` + `attack`): when set, the attack handler uses
     # this verbatim to-hit instead of ability + proficiency + weapon. None otherwise.
     attack_bonus_override: int | None = None
+    # Cast level forced by a variable-charge item invocation (wand upcast):
+    # ``base activity level + extra charges``. When set, resolve_cast uses it
+    # verbatim (bounds-checked) instead of the activity/spell level. None for
+    # every non-item cast.
+    cast_level_override: int | None = None
     # Player-supplied damage-type choice per activity id, for parts that offer a
     # CHOICE of damage type (``DamagePartBlock.types`` with >1 entry — e.g.
     # Chromatic Orb's [acid, cold, fire, ...]). Keyed by activity id; the chosen

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/events.py

@@ -84,6 +84,13 @@ CastFailedReason = Literal[
     # rest. Mirrors the ``no_action_economy`` reject shape, extended from a
     # per-turn budget to a per-encounter / per-rest one.
     "no_uses_remaining",
+    # SRD 5.2 §Charges — a charged item invoked with fewer charges remaining
+    # than the activity's cost (``consumption.targets[type=itemUses]``).
+    "no_charges_remaining",
+    # A variable-charge invocation that violates the activity's
+    # ``consumption.scaling`` contract (not allowed, below base cost, or
+    # above the evaluated max). Emitted by the use_item charge gate.
+    "invalid_charge_spend",
 ]
 
 IntentType = Literal[

{dnd5e_engine-0.2.0 → dnd5e_engine-0.3.1}/src/dnd5e_engine/lib_loader.py

@@ -25,7 +25,16 @@ def set_lib_loader_for_tests(loader: AssetLoader | None) -> None:
     _LIB_LOADER = loader
 
 
+def configure_lib_loader(loader: AssetLoader | None) -> None:
+    """Public host seam: install a custom AssetLoader (e.g. a homebrew
+    overlay). ``None`` reverts to the lazy bundled default. Hosts must
+    call this before start_combat; swapping mid-combat is unsupported."""
+    global _LIB_LOADER
+    _LIB_LOADER = loader
+
+
 __all__ = [
+    "configure_lib_loader",
     "get_lib_loader",
     "set_lib_loader_for_tests",
 ]