Migrating from 0.3.x to 0.4.0
0.4.0 deprecates the legacy rules surface that the initial release inherited
from its first host application. Nothing is removed in 0.4.0; every deprecated
import now emits a DeprecationWarning. 0.5.0 removes it.
Both workspace packages (dnd5e-engine and dnd5e-srd-data) and
nat20-bridge version in lockstep from 0.3.x to 0.4.0. The dataset and the
bridge have no changes of their own in this release.
Why
The package shipped two implementations of the same SRD rules side by side:
the documented engine (orchestrator + activities/, typed Activity corpus,
seeded RNG) and an undocumented legacy layer (dispatch + rules/combat and
friends: dict-shaped inputs, process-global random). They drifted — the
0.3.1 crit-under-disadvantage fix existed only in the legacy path — the legacy
path is not seedable, so the "same seed, same outcome" guarantee never applied
to it, and several of its types are host transport/persistence shapes that
contradict the package's zero-I/O, host-agnostic contract. From 0.4.0 the
engine has exactly one supported rules implementation.
What is deprecated, and where to go
| Deprecated | Route |
|---|---|
dnd5e_engine.dispatch — resolve_combat_action, DispatchContext, CombatResolverResult |
start_combat / submit_player_intent / advance_monster_turn (dnd5e_engine.orchestrator). Attack, cast and check intents resolve through the typed Activity corpus. |
dnd5e_engine.rules.combat — attack_roll, damage_roll, resolve_player_attack, saving_throw, apply_damage, apply_healing, initiative_roll, … |
dnd5e_engine.activities.attack.resolve_attack, activities.damage.resolve_damage, activities.save.resolve_save, activities.heal.resolve_heal, activities.apply.apply_damage — all seeded through ActivityResolutionContext.rng. |
dnd5e_engine.rules.combat_data — weapon_attack_bonus, spell_attack_bonus, spell_save_dc, calculate_cantrip_dice, is_weapon_proficient, CASTER_CLASS_SLUGS, … |
dnd5e_engine.activities.build_context derives every one of these from CharacterBuildSpec plus the dataset; class spellcasting tables live on dnd5e_srd_data class entries. |
dnd5e_engine.rules.combat_helpers — extract_template_combat_stats, build_combat_npc_from_template, build_combatant_from_npc, roll_and_sort_initiative, health_descriptor |
These parse host database records. Copy them into your host (MIT). DeathSaveState moved to dnd5e_engine.death_saves and is not deprecated. |
dnd5e_engine.rules.equipment — calculate_ac, is_armor_proficient |
build_party_member / activities.build_context compute AC from the equipped Armor entries. |
dnd5e_engine.rules.gambits — resolve_monster_action, select_action, assign_behavior_profile, parse_damage_dice, GambitAction, MonsterActionResult |
advance_monster_turn + activities.monster_actions (multiattack-aware). BehaviorProfile moved to dnd5e_engine.types.combat and is not deprecated. |
dnd5e_engine.rules.resolution — parse_ability_scores, build_dice_outcome, classify_roll_type, calculate_natural_roll, … |
Host persistence parsing — copy into your host. |
dnd5e_engine.rules.spells — spell_slots_for_class, SpellSlotState, can_cast, expend_slot, upcast_bonus_dice, concentration_check |
dnd5e_engine.rest + recover_feature_uses; slot tables come from the dataset's class entries; concentration is an engine effect (see Effects). |
dnd5e_engine.event_dicts.event_to_dict |
CombatEvent is a Pydantic model: event.model_dump(mode="json"). |
dnd5e_engine.types.dice.DiceOutcome |
A server→client websocket payload — copy into your host. |
dnd5e_engine.types.intent — ActionType, CombatOutcome, SkillOutcome, SavingThrowOutcome |
ActionType is a host parser vocabulary — copy it. The outcome wire models are superseded by CombatEvents and by dnd5e_engine.CombatOutcome (the end-of-combat record, unrelated to the wire model of the same name). |
dnd5e_engine.types.CombatNPC |
A host-side sidecar record — copy into your host. |
dnd5e_engine.ActionType (top-level) and dnd5e_engine.types.{ActionType, CombatOutcome, DiceOutcome, CombatNPC} |
Still resolve in 0.4.x via a lazy __getattr__ that warns on access; gone in 0.5.0. |
Not deprecated: rules.dice, rules.conditions, rules.skills,
rules.effects, check, death_saves, rest, types.combat.Combatant,
types.effects, types.conditions — the supported engine uses them.
If you still need the legacy code
It is MIT-licensed. Vendor the modules you use into your host from a 0.4.x
checkout, keep the imports of the supported modules above pointing at
dnd5e_engine, and pin dnd5e-engine>=0.4,<0.5 until you have moved onto the
orchestrator. Silence the warnings meanwhile with
-W "ignore::DeprecationWarning:dnd5e_engine".
Moves (old location still re-exports until 0.5.0)
DeathSaveState:rules.combat_helpers→dnd5e_engine.death_savesBehaviorProfile:rules.gambits→dnd5e_engine.types.combat