dndkit 0.4.0__py3-none-any.whl

dndkit/game/bestiary.py

@@ -0,0 +1,155 @@
+"""The bestiary (saved stat blocks) and planned encounters rated against the party."""
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import battlefield, grid, registry, rules, seating
+from dndkit.models import Battlefield, Campaign, Encounter, EncounterGroup, Monster
+
+MONSTER_KIND = "monster"
+ENCOUNTER_KIND = "encounter"
+_NUMBER_SUFFIX = re.compile(r"\s+\d+$")
+
+# What to do when the bestiary lacks a monster: a small model otherwise stops there.
+NEW_MONSTER = " To add it: save_monster (in the dnd-monsters skill), with its book numbers."
+
+
+def find_monster(campaign: Campaign, ref: str) -> Monster:
+    """The bestiary entry *ref* names."""
+    return registry.find(campaign.monsters, ref, MONSTER_KIND, NEW_MONSTER)
+
+
+def monster_for(campaign: Campaign, name: str) -> Monster | None:
+    """The bestiary entry a combatant name stands for: "Goblin 2" is a Goblin."""
+    found = registry.find_exact(campaign.monsters, name)
+    return found or registry.find_exact(campaign.monsters, _NUMBER_SUFFIX.sub("", name))
+
+
+def save_monster(campaign: Campaign, name: str, fields: Mapping[str, Any]) -> tuple[Monster, bool]:
+    """Create or update a stat block; XP follows the challenge rating unless given.
+
+    Returns the monster and whether it is new.
+    """
+    values = dict(fields)
+    challenge = values.get("challenge_rating")
+    if challenge is not None and values.get("xp") is None:
+        xp = rules.xp_for_challenge(challenge)
+        if xp is None:
+            raise InvalidChangeError(f"Unknown challenge rating '{challenge}'; use 0-30 or 1/8.")
+        values["xp"] = xp
+    values = {key: value for key, value in values.items() if value is not None}
+    existing = registry.find_exact(campaign.monsters, name)
+    if existing is not None:
+        return registry.update(campaign.monsters, existing.id, MONSTER_KIND, values), False
+    _fill_from_challenge(values)
+    if values.get("boss"):  # a 5e boss is usually a legendary creature
+        values.setdefault("legendary_actions", 3)
+        values.setdefault("legendary_resistances", 3)
+    missing = [key for key in ("armor_class", "hit_points") if key not in values]
+    if missing:
+        known = registry.known_names(campaign.monsters.values())
+        raise InvalidChangeError(
+            f"A new monster needs {' and '.join(missing)}, or a challenge_rating to set them. "
+            f"To change one, give its full name: {known}."
+        )
+    return registry.add(
+        campaign.monsters, Monster(name=name.strip(), **values), MONSTER_KIND
+    ), True
+
+
+def _fill_from_challenge(values: dict[str, Any]) -> None:
+    """What a new monster lacks, from its challenge rating (DMG ch. 9)."""
+    stats = rules.monster_stats(values.get("challenge_rating") or "")
+    if stats is None:
+        return
+    values.setdefault("armor_class", stats.armor_class)
+    values.setdefault("hit_points", stats.hit_points)
+    values.setdefault(
+        "actions",
+        f"Attack +{stats.attack_bonus}, about {stats.damage_per_round} damage a round "
+        f"(split between its attacks), save DC {stats.save_dc}.",
+    )
+
+
+def _check_squares(
+    campaign: Campaign, field: Battlefield | None, groups: Sequence[Mapping[str, Any]]
+) -> None:
+    """Planned squares must be on the encounter's map, off its walls, one creature each."""
+    planned = [(g["monster"], square) for g in groups for square in g.get("at") or []]
+    if not planned:
+        return
+    if field is None:
+        raise InvalidChangeError("Squares need a map: give the encounter a battlefield.")
+    taken = battlefield.wall_squares(field)
+    for group in groups:
+        if len(group.get("at") or []) > group["count"]:
+            raise InvalidChangeError(f"More squares than {group['monster']} monsters.")
+    for monster, square in planned:
+        size = find_monster(campaign, monster).size
+        held = set(grid.footprint(grid.parse(square, field), size))
+        if held & taken or any(not grid.inside(s, field) for s in held):
+            raise InvalidChangeError(f"{monster} cannot stand on {square.upper()}.")
+        taken |= held
+
+
+def walking_speed(monster: Monster) -> int | None:
+    """The walking speed in a stat block's speed text ("30 ft., fly 60 ft." -> 30)."""
+    match = re.match(r"\s*(\d+)", monster.speed or "")
+    return int(match.group(1)) if match else None
+
+
+def find_encounter(campaign: Campaign, ref: str) -> Encounter:
+    """The planned encounter *ref* names."""
+    return registry.find(campaign.encounters, ref, ENCOUNTER_KIND)
+
+
+def plan_encounter(
+    campaign: Campaign,
+    name: str,
+    groups: Sequence[EncounterGroup] | None,
+    fields: Mapping[str, Any],
+) -> tuple[Encounter, bool]:
+    """Create or update an encounter; its monsters must be in the bestiary."""
+    values = {key: value for key, value in fields.items() if value is not None}
+    if groups is not None:
+        # One error naming every unknown monster, then the bestiary's own spelling.
+        registry.find_many(
+            campaign.monsters, [g.monster for g in groups], MONSTER_KIND, NEW_MONSTER
+        )
+        values["monsters"] = [
+            {**g.model_dump(), "monster": find_monster(campaign, g.monster).name} for g in groups
+        ]
+    existing = registry.find_exact(campaign.encounters, name)
+    _check_squares(
+        campaign,
+        values.get("battlefield") or (existing.battlefield if existing else None),
+        values.get("monsters") or (existing.model_dump()["monsters"] if existing else []),
+    )
+    if existing is not None:
+        return registry.update(campaign.encounters, existing.id, ENCOUNTER_KIND, values), False
+    if not values.get("monsters"):
+        known = registry.known_names(campaign.encounters.values())
+        raise InvalidChangeError(
+            f"A new encounter needs its monsters. To change one, give its full name: {known}."
+        )
+    encounter = Encounter.model_validate({"name": name.strip(), **values})
+    return registry.add(campaign.encounters, encounter, ENCOUNTER_KIND), True
+
+
+def difficulty(campaign: Campaign, encounter: Encounter) -> rules.Difficulty | None:
+    """The encounter rated against the characters at the table; None without any.
+
+    Two players out of four make a medium fight a deadly one: absent players'
+    characters do not count, once there has been a roll call (``seating``).
+    """
+    levels = [c.character_class.level for c in seating.present_characters(campaign)]
+    if not levels:
+        return None
+    xps = [
+        find_monster(campaign, group.monster).xp
+        for group in encounter.monsters
+        for _ in range(group.count)
+    ]
+    return rules.encounter_difficulty(levels, xps)

dndkit/game/characters.py

@@ -0,0 +1,227 @@
+"""Creating, changing and removing player characters."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import proficiencies, registry, rules
+from dndkit.models import ABILITIES, Campaign, Character, now
+
+KIND = "character"
+
+
+def find(campaign: Campaign, ref: str) -> Character:
+    """The character *ref* names (name or ID)."""
+    return registry.find(campaign.characters, ref, KIND)
+
+
+@dataclass(frozen=True)
+class Spellcasting:
+    """How a character casts: the ability, the spell attack bonus and the save DC."""
+
+    ability: str
+    attack: int
+    save_dc: int
+
+
+def pick(campaign: Campaign, ref: str | None) -> Character:
+    """The character *ref* names; without one, whose turn it is, or the only character."""
+    if ref:
+        return find(campaign, ref)
+    current = campaign.game_state.current_combatant
+    if current is not None and current.character_id in campaign.characters:
+        return campaign.characters[current.character_id]
+    if len(campaign.characters) == 1:
+        return next(iter(campaign.characters.values()))
+    names = registry.known_names(campaign.characters.values())
+    raise InvalidChangeError(f"Which character? Characters: {names}.")
+
+
+def create(campaign: Campaign, character: Character) -> Character:
+    """Add a character with what its class and level give: proficiency, hit dice, a
+    caster's slots and casting ability. The name must be free."""
+    cls = character.character_class
+    if character.spellcasting_ability is None:
+        character.spellcasting_ability = rules.casting_ability(cls.name)
+    die = rules.hit_die(cls.name)
+    character.character_class = cls.model_copy(update={"hit_dice": f"1d{die}"})
+    character.hit_dice_remaining = f"{cls.level}d{die}"
+    character.proficiency_bonus = rules.proficiency_bonus(cls.level)
+    if not character.saving_throw_proficiencies:
+        character.saving_throw_proficiencies = rules.class_saves(cls.name)
+    if not character.spell_slots:
+        character.spell_slots = rules.spell_slots_for(cls.name, cls.level) or {}
+    return registry.add(campaign.characters, character, KIND)
+
+
+def level_edits(character: Character, level: int) -> dict[str, Any]:
+    """What follows a level set by hand: proficiency, hit dice and spell slots (spent
+    ones stay spent). Hit points do not: ``level_up`` gains a level in full."""
+    cls = character.character_class
+    die = rules.hit_die(cls.name)
+    edits: dict[str, Any] = {
+        "character_class": {**cls.model_dump(), "level": level, "hit_dice": f"1d{die}"},
+        "proficiency_bonus": rules.proficiency_bonus(level),
+        "hit_dice_remaining": f"{level}d{die}",
+    }
+    slots = rules.spell_slots_for(cls.name, level)
+    if slots is not None:
+        edits["spell_slots"] = dict(slots)
+        edits["spell_slots_used"] = slots_still_used(character, slots)
+    return edits
+
+
+def hit_dice_left(character: Character) -> int:
+    """How many Hit Dice are left ("3d8" -> 3); 0 if the sheet says something else."""
+    match = re.match(r"\s*(\d+)\s*d", character.hit_dice_remaining)
+    return int(match.group(1)) if match else 0
+
+
+def slots_still_used(character: Character, slots: Mapping[int, int]) -> dict[int, int]:
+    """The spent slots that remain spent once the character has *slots*."""
+    used = character.spell_slots_used
+    return {lvl: min(count, slots[lvl]) for lvl, count in used.items() if lvl in slots}
+
+
+def spellcasting(character: Character) -> Spellcasting | None:
+    """Spell attack bonus and save DC (PHB ch. 10); None for a character who casts nothing."""
+    ability = rules.ability_name(character.spellcasting_ability) or rules.casting_ability(
+        character.character_class.name
+    )
+    if ability is None or ability not in character.abilities:
+        return None
+    bonus = character.proficiency_bonus + character.abilities[ability].mod
+    return Spellcasting(ability, bonus, 8 + bonus)
+
+
+def initiative(character: Character) -> int:
+    """The initiative bonus: the Dexterity modifier, and a bard's Jack of All Trades."""
+    dexterity = character.abilities.get("dexterity")
+    return (dexterity.mod if dexterity else 0) + proficiencies.jack_of_all_trades(character)
+
+
+def _skill_edits(character: Character, edits: Mapping[str, Any]) -> dict[str, list[str]]:
+    """Skills and Expertise checked together: Expertise only in a proficient skill, and
+    a skill dropped from the list loses its Expertise."""
+    proficient = character.skill_proficiencies
+    checked: dict[str, list[str]] = {}
+    if "skill_proficiencies" in edits:
+        proficient = proficiencies.skills(edits["skill_proficiencies"])
+        checked["skill_proficiencies"] = proficient
+    if "skill_expertise" in edits:
+        checked["skill_expertise"] = proficiencies.expertise(edits["skill_expertise"], proficient)
+    else:
+        kept = {proficiencies.skill_name(name) for name in proficient}
+        checked["skill_expertise"] = [
+            s for s in character.skill_expertise if proficiencies.skill_name(s) in kept
+        ]
+    return checked
+
+
+def remove(campaign: Campaign, ref: str) -> Character:
+    """Remove a character from the campaign."""
+    return registry.remove(campaign.characters, ref, KIND)
+
+
+def update(
+    campaign: Campaign,
+    ref: str,
+    changes: Mapping[str, Any],
+    abilities: Mapping[str, int],
+) -> Character:
+    """Apply sheet changes; ``class_level`` and ability scores go to their nested fields."""
+    character = find(campaign, ref)
+    edits = dict(changes)
+    level = edits.pop("class_level", None)
+    if level is not None:
+        edits.update(level_edits(character, level))
+    if edits.get("exhaustion") == 6:  # PHB appendix A: death
+        edits.update(hit_points_current=0, death_saves_failure=3, stable=False)
+    if character.hit_points_current == 0 and edits.get("hit_points_current", 0) > 0:
+        # Back from 0 HP by hand (a spell that raises the dead): a fresh start.
+        edits.update(death_saves_success=0, death_saves_failure=0, stable=False)
+        edits.setdefault("conditions", [c for c in character.conditions if c != "unconscious"])
+    if "skill_proficiencies" in edits or "skill_expertise" in edits:
+        edits.update(_skill_edits(character, edits))
+    if "saving_throw_proficiencies" in edits:
+        edits["saving_throw_proficiencies"] = proficiencies.saves(
+            edits["saving_throw_proficiencies"]
+        )
+    if abilities:
+        unknown = sorted(set(abilities) - set(ABILITIES))
+        if unknown:
+            raise InvalidChangeError(f"Unknown abilities: {', '.join(unknown)}.")
+        scores = {name: score.model_dump() for name, score in character.abilities.items()}
+        scores.update({name: {"score": value} for name, value in abilities.items()})
+        edits["abilities"] = scores
+    _cap_hit_points(character, edits)
+    edits["updated_at"] = now()
+    return registry.update(campaign.characters, character.id, KIND, edits)
+
+
+def _cap_hit_points(character: Character, edits: dict[str, Any]) -> None:
+    """Refuse current HP above the maximum; a lowered maximum (or exhaustion 4)
+    lowers current HP."""
+    maximum = edits.get("hit_points_max", character.hit_points_max)
+    if edits.get("exhaustion", character.exhaustion) >= 4:
+        maximum = max(1, maximum // 2)
+    current = edits.get("hit_points_current")
+    if current is None:
+        edits["hit_points_current"] = min(character.hit_points_current, maximum)
+    elif current > maximum:
+        raise InvalidChangeError(
+            f"{character.name}'s current HP ({current}) cannot exceed max HP ({maximum})."
+        )
+
+
+def change_hp(character: Character, delta: int) -> str:
+    """Heal or damage one character, following the 0 HP rules (PHB ch. 9)."""
+    was_down = character.hit_points_current == 0
+    if delta > 0 and character.death_saves_failure >= 3:
+        raise InvalidChangeError(
+            f"{character.name} is dead: healing does not bring them back. If a spell does "
+            "(revivify, raise dead), set their hit points with update_character."
+        )
+    maximum = character.hp_maximum
+    hp = rules.apply_hp_change(
+        character.hit_points_current, maximum, character.temporary_hit_points, delta
+    )
+    overflow = -delta - (character.temporary_hit_points - hp.temporary)
+    overflow -= character.hit_points_current
+    character.hit_points_current = hp.current
+    character.temporary_hit_points = hp.temporary
+    character.updated_at = now()
+    status = f"{character.name}: HP {hp.current}/{maximum}"
+    if delta > 0:
+        return _healed(character, status) if was_down and hp.current > 0 else status
+    if hp.current > 0:
+        return status
+    if overflow >= maximum:
+        character.death_saves_failure, character.stable = 3, False
+        return f"{status}, killed outright by massive damage"
+    if was_down:
+        character.death_saves_failure = min(3, character.death_saves_failure + 1)
+        character.stable = False
+        return (
+            f"{status}, hit while down: {character.death_saves_failure}/3 death save failures "
+            "(a critical hit counts two: record_death_save failure once more)"
+        )
+    _add_conditions(character, "unconscious", "prone")
+    return f"{status}, unconscious and prone: death saving throws from now on"
+
+
+def _healed(character: Character, status: str) -> str:
+    character.death_saves_success = 0
+    character.death_saves_failure = 0
+    character.stable = False
+    character.conditions = [c for c in character.conditions if c != "unconscious"]
+    return f"{status}, conscious again (still prone; death saves reset)"
+
+
+def _add_conditions(character: Character, *names: str) -> None:
+    character.conditions = [
+        *character.conditions,
+        *(n for n in names if n not in character.conditions),
+    ]

dndkit/game/combat.py

@@ -0,0 +1,209 @@
+"""The initiative order: whose turn it is, by position rather than by name.
+
+Turns are tracked by index, so three goblins each get their turn; same-named
+combatants are numbered ("Goblin 1", "Goblin 2") so they can be told apart
+aloud. Foes who fall or flee move to ``defeated``, which the end of the combat
+turns into an XP total; the party and its allies earn none.
+"""
+
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from dndkit.errors import InvalidChangeError, NotFoundError
+from dndkit.game import registry
+from dndkit.game.combatants import number_duplicates, unique_name
+from dndkit.models import Combatant, CombatRecord, GameState
+
+
+@dataclass(frozen=True)
+class CombatSummary:
+    """What a finished combat leaves: its length and who was overcome."""
+
+    rounds: int
+    defeated: list[Combatant]
+    xp: int
+
+
+def start(
+    state: GameState, combatants: Sequence[Combatant], encounter_id: str | None = None
+) -> Combatant:
+    """Sort by initiative (ties keep the given order) and open round 1."""
+    if state.in_combat:
+        raise InvalidChangeError("A combat is already running. Use add_combatant or end_combat.")
+    if state.combat_round:
+        raise InvalidChangeError("The last fight was not closed: call end_combat first.")
+    if not combatants:
+        raise InvalidChangeError("A combat needs at least one participant.")
+    linked = Counter(c.character_id for c in combatants if c.character_id)
+    twice = sorted({c.name for c in combatants if c.character_id and linked[c.character_id] > 1})
+    if twice:
+        raise InvalidChangeError(f"Given twice: {', '.join(twice)}. Name each one once.")
+    ordered = sorted(combatants, key=lambda c: c.initiative, reverse=True)
+    state.initiative_order = number_duplicates(ordered)
+    state.in_combat = True
+    state.turn_index = 0
+    state.combat_round = 1
+    state.defeated = []
+    state.encounter_id = encounter_id
+    return state.initiative_order[0]
+
+
+def add(state: GameState, combatant: Combatant) -> Combatant:
+    """Insert a newcomer by initiative without changing whose turn it is."""
+    _require_combat(state)
+    if combatant.character_id and any(
+        c.character_id == combatant.character_id for c in state.initiative_order
+    ):
+        raise InvalidChangeError(f"{combatant.name} is already in the fight.")
+    if combatant.character_id is None:
+        name = unique_name(state.initiative_order, combatant.name)
+        combatant = combatant.model_copy(update={"name": name})
+    order = state.initiative_order
+    position = next(
+        (i for i, c in enumerate(order) if combatant.initiative > c.initiative), len(order)
+    )
+    state.initiative_order = [*order[:position], combatant, *order[position:]]
+    if position <= state.turn_index:
+        state.turn_index += 1
+    return combatant
+
+
+def next_turn(state: GameState) -> Combatant:
+    """Advance one turn; passing the last combatant starts a new round."""
+    _require_combat(state)
+    state.turn_index += 1
+    if state.turn_index >= len(state.initiative_order):
+        state.turn_index = 0
+        state.combat_round += 1
+    if state.battlefield is not None:  # the last area of effect is spent
+        state.battlefield.area, state.battlefield.area_label = [], None
+    return _begin_turn(state.initiative_order[state.turn_index])
+
+
+def find(state: GameState, name: str) -> Combatant:
+    """The combatant *name* names (case and accents ignored), or the only one whose
+    name holds it ("gardien" for "Gardien de Magma"), as spoken names go."""
+    _require_combat(state)
+    found = find_optional(state, name)
+    if found is None:
+        names = [c.name for c in state.initiative_order]
+        near = registry.did_you_mean(names, name)
+        raise NotFoundError(
+            f"No combatant named '{name}'.{near} In the fight: {', '.join(names)}."
+        )
+    return found
+
+
+def find_optional(state: GameState, name: str) -> Combatant | None:
+    """Like ``find``, or None."""
+    wanted = registry.normalize(name)
+    for combatant in state.initiative_order:
+        if registry.normalize(combatant.name) == wanted:
+            return combatant
+    partial = registry.partial_matches(state.initiative_order, name)
+    return partial[0] if len(partial) == 1 else None
+
+
+def remove(
+    state: GameState, name: str, overcome: bool = True
+) -> tuple[Combatant, Combatant | None]:
+    """Take a combatant out of the fight and off the map; returns it and whoever acts now.
+
+    An *overcome* foe (fallen or fled) joins the defeated and counts for XP; one
+    taken back (a mistake, a change of plan) leaves no trace. Removing the last
+    combatant ends the combat and returns None as the second value.
+    """
+    removed = find(state, name)
+    index = next(i for i, c in enumerate(state.initiative_order) if c is removed)
+    state.initiative_order = [c for c in state.initiative_order if c is not removed]
+    if overcome and removed.character_id is None and not removed.ally:
+        state.defeated = [*state.defeated, removed]
+    if not state.initiative_order:
+        state.in_combat = False
+        return removed, None
+    if index < state.turn_index:
+        state.turn_index -= 1
+    elif index == state.turn_index:  # the one acting left: the next one's turn starts
+        if state.turn_index >= len(state.initiative_order):
+            state.turn_index = 0
+            state.combat_round += 1
+        _begin_turn(state.initiative_order[state.turn_index])
+    return removed, state.initiative_order[state.turn_index]
+
+
+def end(state: GameState) -> CombatSummary:
+    """Close the combat, or what is left of one whose last combatant was removed;
+    the summary lists who was overcome and their total XP."""
+    if not state.in_combat and not state.combat_round:
+        raise InvalidChangeError("No combat is running.")
+    summary = CombatSummary(
+        rounds=state.combat_round,
+        defeated=list(state.defeated),
+        xp=sum(c.xp for c in state.defeated),
+    )
+    state.last_combat = CombatRecord(
+        rounds=summary.rounds,
+        fighters=[c.name for c in [*state.initiative_order, *state.defeated]],
+        defeated=[c.name for c in summary.defeated],
+        xp=summary.xp,
+    )
+    state.in_combat = False
+    state.initiative_order = []
+    state.turn_index = 0
+    state.combat_round = 0
+    state.defeated = []
+    state.encounter_id = None
+    state.battlefield = None  # the next fight lays out its own
+    return summary
+
+
+def _begin_turn(combatant: Combatant) -> Combatant:
+    """A turn starts with the full movement, no Dash or Disengage yet, the reaction
+    and the legendary actions back (MM, "Legendary Creatures")."""
+    combatant.movement_used = 0
+    combatant.dashed = False
+    combatant.disengaged = False
+    combatant.reaction_used = False
+    combatant.legendary_actions_left = combatant.legendary_actions
+    return combatant
+
+
+def use_legendary(state: GameState, name: str, resistance: bool, cost: int) -> Combatant:
+    """Spend a legendary action (*cost* of them) or a legendary resistance."""
+    creature = find(state, name)
+    if resistance:
+        if creature.legendary_resistances_left < 1:
+            raise InvalidChangeError(f"{creature.name} has no legendary resistance left.")
+        creature.legendary_resistances_left -= 1
+        return creature
+    if not creature.legendary_actions:
+        raise InvalidChangeError(f"{creature.name} has no legendary actions.")
+    if creature is state.current_combatant:
+        raise InvalidChangeError("Legendary actions come at the end of another creature's turn.")
+    if creature.legendary_actions_left < cost:
+        raise InvalidChangeError(
+            f"{creature.name} has {creature.legendary_actions_left} legendary action(s) left "
+            "this round; they come back at the start of its turn."
+        )
+    creature.legendary_actions_left -= cost
+    return creature
+
+
+def use_reaction(state: GameState, name: str, able: bool) -> Combatant:
+    """Spend a combatant's reaction for the round; *able*: it can react at all."""
+    creature = find(state, name)
+    if creature.reaction_used:
+        raise InvalidChangeError(
+            f"{creature.name} has used its reaction this round; it comes back at the "
+            "start of its turn."
+        )
+    if not able:
+        raise InvalidChangeError(f"{creature.name} cannot react: down or incapacitated.")
+    creature.reaction_used = True
+    return creature
+
+
+def _require_combat(state: GameState) -> None:
+    if not state.in_combat or not state.initiative_order:
+        raise InvalidChangeError("No combat is running. Start one with start_combat.")