dndkit 0.4.0__py3-none-any.whl

dndkit/game/readiness.py

@@ -0,0 +1,214 @@
+"""What a campaign still lacks before it is played, by the 5e rules (SRD 5.1).
+
+The checks read the campaign and say what is wrong or missing, each with the
+tool that fixes it. They change nothing: a game master may keep a fighter
+without armor on purpose. ``certain`` findings break a rule; the others are
+what a first campaign usually forgets.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from dndkit.game import bestiary, registry, rules
+from dndkit.models import ABILITIES, Campaign, Character, Encounter
+
+# The armor in each class's starting equipment, for a sheet still at 10 + DEX.
+STARTING_ARMOR = {
+    "artificer": "studded leather (AC 12 + DEX) or scale mail (14 + DEX, max 2)",
+    "bard": "leather armor (AC 11 + DEX)",
+    "cleric": "scale mail and a shield (AC 16 + DEX, max 2)",
+    "druid": "leather armor and a wooden shield (AC 13 + DEX)",
+    "fighter": "chain mail (AC 16, 18 with a shield)",
+    "paladin": "chain mail (AC 16, 18 with a shield)",
+    "ranger": "scale mail (AC 14 + DEX, max 2) or leather (11 + DEX)",
+    "rogue": "leather armor (AC 11 + DEX)",
+    "warlock": "leather armor (AC 11 + DEX)",
+}
+# Unarmored Defense: AC 10 + DEX + this ability's modifier.
+UNARMORED_DEFENSE = {"barbarian": "constitution", "monk": "wisdom"}
+STANDARD_ARRAY = "15, 14, 13, 12, 10, 8"
+# Hit points a feature may add per level (Tough, a hill dwarf's toughness).
+EXTRA_HP_PER_LEVEL = 3
+# Expertise in two skills at each of these class levels.
+EXPERTISE_LEVELS = {"rogue": (1, 6), "bard": (3, 10)}
+
+
+@dataclass(frozen=True)
+class Finding:
+    subject: str  # a character, a quest, a monster, or the campaign
+    problem: str
+    fix: str  # the call that fixes it
+    certain: bool  # breaks a rule, rather than likely forgotten
+
+
+def check(campaign: Campaign) -> list[Finding]:
+    """Everything worth fixing before play: the campaign, each character, the bestiary."""
+    found = _world(campaign)
+    for character in campaign.characters.values():
+        found += [f for check in CHARACTER_CHECKS if (f := check(character))]
+    return found + _bestiary(campaign)
+
+
+def _world(campaign: Campaign) -> list[Finding]:
+    name = campaign.name
+    found: list[Finding] = []
+    if not campaign.characters:
+        found.append(Finding(name, "no characters", "create_character for each player", True))
+    if not any(q.status == "active" for q in campaign.quests.values()):
+        found.append(Finding(name, "no active quest: the story's hook", "create_quest", False))
+    if not campaign.npcs:
+        found.append(Finding(name, "no NPC to meet first", "create_npc", False))
+    found += _whereabouts(campaign)
+    for quest in campaign.quests.values():
+        if quest.giver and not registry.find_exact(campaign.npcs, quest.giver):
+            problem = f"given by {quest.giver}, who is no NPC"
+            found.append(Finding(f"quest {quest.title}", problem, "create_npc", False))
+    return found
+
+
+def _whereabouts(campaign: Campaign) -> list[Finding]:
+    here = campaign.game_state.current_location
+    if here and registry.find_exact(campaign.locations, here):
+        return []
+    if here:
+        problem, fix = f"the party is at {here}, which is no location", f"create_location {here}"
+    elif campaign.locations:
+        problem, fix = "the party is nowhere", "update_game_state current_location"
+    else:
+        problem, fix = "no location", "create_location, then update_game_state current_location"
+    return [Finding(campaign.name, problem, fix, False)]
+
+
+def _class(c: Character) -> Finding | None:
+    if rules.class_key(c.character_class.name):
+        return None
+    problem = (
+        f"{c.character_class.name} is no 5e class: its hit dice, saves and spells are guesses"
+    )
+    fix = "remove_from_campaign, then create_character with a class from the book"
+    return Finding(c.name, problem, fix, True)
+
+
+def _armor(c: Character) -> Finding | None:
+    key = rules.class_key(c.character_class.name) or ""
+    unarmored = 10 + c.abilities["dexterity"].mod
+    if key in UNARMORED_DEFENSE:
+        ability = UNARMORED_DEFENSE[key]
+        least = unarmored + c.abilities[ability].mod
+        if c.armor_class < least:
+            short = ability[:3].upper()
+            problem = f"AC {c.armor_class}, below Unarmored Defense (10 + DEX + {short} = {least})"
+            return Finding(c.name, problem, "update_character armor_class", True)
+    elif key in STARTING_ARMOR and c.armor_class <= unarmored:
+        problem = f"AC {c.armor_class} is no armor; a {key} starts with {STARTING_ARMOR[key]}"
+        return Finding(c.name, problem, "update_character armor_class", False)
+    return None
+
+
+def _abilities(c: Character) -> Finding | None:
+    unset = [a[:3].upper() for a in ABILITIES if c.abilities[a].score == 10]
+    if len(unset) < 3:
+        return None
+    problem = f"{', '.join(unset)} still 10, as if never set (standard array {STANDARD_ARRAY})"
+    return Finding(c.name, problem, "update_character with the scores", False)
+
+
+def _hit_points(c: Character) -> Finding | None:
+    """Within what the hit dice allow: the whole die at level 1, then 1 to the die."""
+    cls = c.character_class
+    if not rules.class_key(cls.name):
+        return None
+    die, con, level = rules.hit_die(cls.name), c.abilities["constitution"].mod, cls.level
+    least = max(1, die + con) + (level - 1) * max(1, 1 + con)
+    most = level * (die + con + EXTRA_HP_PER_LEVEL)
+    if least <= c.hit_points_max <= most:
+        return None
+    average = rules.starting_hit_points(cls.name, level, con)
+    problem = (
+        f"{c.hit_points_max} hit points, outside what a level {level} {cls.name} with CON "
+        f"{con:+d} can have ({least} to {most}); by the averages, {average}"
+    )
+    return Finding(c.name, problem, "update_character hit_points_max", True)
+
+
+def _expertise(c: Character) -> Finding | None:
+    """A rogue's or a bard's Expertise (or thieves' tools for a rogue, hence not certain)."""
+    levels = EXPERTISE_LEVELS.get(rules.class_key(c.character_class.name) or "", ())
+    due = 2 * sum(c.character_class.level >= level for level in levels)
+    if len(c.skill_expertise) >= due:
+        return None
+    problem = f"Expertise in {due} skills by its level, has {len(c.skill_expertise)}"
+    return Finding(c.name, problem, "update_character expertise", False)
+
+
+def _gear(c: Character) -> Finding | None:
+    items = [*c.inventory, *(i for i in c.equipment.values() if i)]
+    if not items:
+        problem = "carries nothing, not even a weapon or a pack"
+    elif not any(i.item_type == "weapon" for i in items):
+        problem = "carries no weapon"
+    else:
+        return None
+    return Finding(c.name, problem, "add_item_to_character with its item_type", False)
+
+
+def _spells(c: Character) -> Finding | None:
+    if not any(c.spell_slots.values()) or c.spells_known:
+        return None
+    problem = "has spell slots but knows no spells, not even a cantrip"
+    return Finding(c.name, problem, "set_known_spell for each", True)
+
+
+def _skills(c: Character) -> Finding | None:
+    if c.skill_proficiencies:
+        return None
+    problem = "no skill proficiencies (2 to 4 from the class, 2 from the background)"
+    return Finding(c.name, problem, "update_character skills", False)
+
+
+def _player(c: Character) -> Finding | None:
+    if c.player_name:
+        return None
+    problem = "no player: the roll call cannot seat it"
+    return Finding(c.name, problem, "update_character player_name", False)
+
+
+CHARACTER_CHECKS: tuple[Callable[[Character], Finding | None], ...] = (
+    _class,
+    _player,
+    _abilities,
+    _hit_points,
+    _armor,
+    _skills,
+    _expertise,
+    _gear,
+    _spells,
+)
+
+
+def _bestiary(campaign: Campaign) -> list[Finding]:
+    found = [
+        Finding(m.name, "no actions: its attacks and their damage", "save_monster actions", False)
+        for m in campaign.monsters.values()
+        if not m.actions.strip()
+    ]
+    levels = [c.character_class.level for c in campaign.characters.values()]
+    planned = [e for e in campaign.encounters.values() if e.status == "planned"]
+    return found + [f for e in planned if (f := _encounter(campaign, e, levels))]
+
+
+def _encounter(campaign: Campaign, encounter: Encounter, levels: list[int]) -> Finding | None:
+    """A planned fight whose monsters are missing, or rated deadly or trivial for the party."""
+    subject = f"encounter {encounter.name}"
+    monsters = [(g, bestiary.monster_for(campaign, g.monster)) for g in encounter.monsters]
+    missing = [g.monster for g, m in monsters if m is None]
+    if missing:
+        return Finding(subject, f"{', '.join(missing)} not in the bestiary", "save_monster", True)
+    if not levels:
+        return None
+    xps = [m.xp for g, m in monsters if m for _ in range(g.count)]
+    rated = rules.encounter_difficulty(levels, xps).rating
+    if rated not in ("deadly", "trivial"):
+        return None
+    problem = f"{rated} for the whole party" + (", for a climax only" if rated == "deadly" else "")
+    return Finding(subject, problem, "plan_encounter with another count", False)

dndkit/game/reference.py

@@ -0,0 +1,123 @@
+"""Short rules reminders (D&D 5e 2014), paraphrased, findable by English or French name."""
+
+from dndkit.errors import NotFoundError
+from dndkit.text import normalize
+
+RULES: dict[str, str] = {
+    "blinded": "Can't see; fails any check that needs sight. Attacks against it have "
+    "advantage, its own attacks have disadvantage.",
+    "charmed": "Can't attack the charmer or target it with harmful abilities or magic. "
+    "The charmer has advantage on social checks against it.",
+    "deafened": "Can't hear; fails any check that needs hearing.",
+    "frightened": "Disadvantage on ability checks and attack rolls while the source of its "
+    "fear is in sight; can't willingly move closer to it.",
+    "grappled": "Speed 0. Ends if the grappler is incapacitated or an effect moves the "
+    "creature out of reach. Escape: an action, Athletics or Acrobatics against the "
+    "grappler's Athletics.",
+    "incapacitated": "Can't take actions or reactions.",
+    "invisible": "Can't be seen without magic or a special sense. Attacks against it have "
+    "disadvantage, its own attacks have advantage.",
+    "paralyzed": "Incapacitated, can't move or speak; fails Strength and Dexterity saves. "
+    "Attacks against it have advantage, and a hit from within 5 feet is a critical hit.",
+    "petrified": "Turned to stone: incapacitated, can't move or speak, unaware. Attacks "
+    "against it have advantage; fails Strength and Dexterity saves; resistance to all "
+    "damage; immune to poison and disease (any already in it is suspended).",
+    "poisoned": "Disadvantage on attack rolls and ability checks.",
+    "prone": "Can only crawl, or stand up for half its movement. Disadvantage on its "
+    "attacks. Attacks against it have advantage within 5 feet, disadvantage beyond.",
+    "restrained": "Speed 0. Attacks against it have advantage, its attacks have "
+    "disadvantage; disadvantage on Dexterity saves.",
+    "stunned": "Incapacitated, can't move, speaks falteringly; fails Strength and Dexterity "
+    "saves. Attacks against it have advantage.",
+    "unconscious": "Incapacitated, can't move or speak, unaware; drops what it holds and "
+    "falls prone; fails Strength and Dexterity saves. Attacks against it have advantage, "
+    "and a hit from within 5 feet is a critical hit.",
+    "exhaustion": "Levels add up: 1 disadvantage on ability checks; 2 speed halved; "
+    "3 disadvantage on attacks and saves; 4 hit point maximum halved; 5 speed 0; "
+    "6 death. A long rest with food and drink removes one level.",
+    "advantage": "Roll two d20 and keep the higher (disadvantage: the lower). Several "
+    "sources don't stack; having both cancels them out.",
+    "death saves": "At 0 HP, roll a d20 at the start of each turn: 10 or more is a "
+    "success, less a failure. Three successes: stable. Three failures: dead. A 1 counts "
+    "as two failures; a 20 brings the creature back with 1 HP. Taking damage at 0 HP is "
+    "a failure (two on a critical hit). Damage left over after 0 HP that equals or "
+    "exceeds the hit point maximum kills outright.",
+    "stabilizing": "An action and a DC 10 Wisdom (Medicine) check stabilize a creature at "
+    "0 HP. A stable creature regains 1 HP after 1d4 hours.",
+    "short rest": "At least one hour. Each character may spend Hit Dice: roll each, add "
+    "the Constitution modifier, regain that many hit points. Warlocks regain pact slots.",
+    "long rest": "At least eight hours, once per 24 hours, starting with at least 1 HP: "
+    "regain all hit points, spell slots and half the total Hit Dice (at least one).",
+    "cover": "Half cover: +2 to AC and Dexterity saves. Three-quarters cover: +5. Total "
+    "cover: can't be targeted directly.",
+    "concentration": "One concentration spell at a time. Taking damage calls for a "
+    "Constitution save, DC 10 or half the damage if higher; failing ends the spell. "
+    "Being incapacitated or killed ends it too.",
+    "opportunity attack": "When a visible enemy leaves your reach, you may use your "
+    "reaction for one melee attack. The Disengage action, teleporting or being moved "
+    "against one's will doesn't provoke it.",
+    "grapple": "Replaces one attack: Athletics against the target's Athletics or "
+    "Acrobatics; the target is at most one size larger. Success: the target is grappled.",
+    "shove": "Replaces one attack: Athletics against Athletics or Acrobatics; the "
+    "target is at most one size larger. Success knocks it prone or pushes it 5 feet away.",
+    "surprise": "Creatures that notice no threat at the start are surprised: no move, "
+    "action or reaction on their first turn.",
+    "initiative": "Each combatant makes a Dexterity check (d20 + Dexterity modifier); "
+    "turns go from highest to lowest. The game master settles ties.",
+    "actions": "In combat a creature can Attack, Cast a Spell, Dash (extra movement), "
+    "Disengage (no opportunity attacks), Dodge (attacks against it have disadvantage), "
+    "Help (an ally gains advantage), Hide, Ready a reaction, Search or Use an Object, plus "
+    "its movement and possibly one bonus action and one reaction per round.",
+    "two-weapon fighting": "After attacking with a light melee weapon, a bonus action "
+    "attack with another light melee weapon; no ability modifier to its damage unless "
+    "negative.",
+    "critical hit": "A natural 20 on an attack roll always hits; roll all the damage dice "
+    "twice, then add modifiers once.",
+    "falling": "1d6 bludgeoning damage per 10 feet fallen, up to 20d6; the creature lands prone.",
+    "suffocating": "Breath can be held for 1 + Constitution modifier minutes (at least 30 "
+    "seconds); after that, the creature lasts Constitution modifier rounds (at least 1) "
+    "before dropping to 0 HP.",
+    "difficult terrain": "Each foot of movement costs one extra foot.",
+    "obscured areas": "Lightly obscured (dim light, fog): disadvantage on Perception by "
+    "sight. Heavily obscured (darkness, thick fog): effectively blinded.",
+    "inspiration": "A character with inspiration may spend it for advantage on one attack "
+    "roll, saving throw or ability check.",
+    "encounter difficulty": "Add the monsters' XP, multiply by a factor for their number "
+    "(x1 for one, x1.5 for two, x2 for 3-6, x2.5 for 7-10, x3 for 11-14, x4 for 15+), "
+    "and compare with the party's easy, medium, hard and deadly thresholds.",
+}
+
+ALIASES: dict[str, str] = {
+    "aveugle": "blinded", "charme": "charmed", "assourdi": "deafened", "sourd": "deafened",
+    "effraye": "frightened", "terrorise": "frightened", "agrippe": "grappled",
+    "empoigne": "grappled", "neutralise": "incapacitated", "incapable d'agir": "incapacitated",
+    "paralyse": "paralyzed", "petrifie": "petrified", "empoisonne": "poisoned",
+    "a terre": "prone", "entrave": "restrained", "etourdi": "stunned",
+    "inconscient": "unconscious", "epuisement": "exhaustion", "desavantage": "advantage",
+    "disadvantage": "advantage", "jets contre la mort": "death saves",
+    "jet contre la mort": "death saves", "death saving throws": "death saves",
+    "stabiliser": "stabilizing", "repos court": "short rest", "repos long": "long rest",
+    "abri": "cover", "couverture": "cover", "attaque d'opportunite": "opportunity attack",
+    "lutte": "grapple", "agripper": "grapple", "bousculer": "shove", "pousser": "shove",
+    "combat a deux armes": "two-weapon fighting", "coup critique": "critical hit",
+    "critique": "critical hit", "chute": "falling", "suffocation": "suffocating",
+    "asphyxie": "suffocating", "terrain difficile": "difficult terrain",
+    "visibilite": "obscured areas", "obscurite": "obscured areas",
+    "actions en combat": "actions", "difficulte des rencontres": "encounter difficulty",
+}  # fmt: skip
+
+_INDEX = {normalize(key): key for key in RULES} | {
+    normalize(alias): key for alias, key in ALIASES.items()
+}
+
+
+def lookup(topic: str) -> tuple[str, str]:
+    """The rule a topic names, as (topic, text); plural and French names work too."""
+    wanted = normalize(topic)
+    key = _INDEX.get(wanted) or _INDEX.get(wanted.rstrip("s"))
+    if key is None:
+        matches = [k for name, k in _INDEX.items() if wanted and wanted in name]
+        key = matches[0] if len(set(matches)) == 1 else None
+    if key is None:
+        raise NotFoundError(f"No rule note on '{topic}'. Topics: {', '.join(RULES)}.")
+    return key, RULES[key]

dndkit/game/registry.py

@@ -0,0 +1,172 @@
+"""Find, add, change and remove campaign entities by ID or by spoken name.
+
+A voice transcript rarely spells a name the way it was typed ("aria",
+"Élodie" heard as "Elodie"), so names match without case or accents. When
+nothing matches, the error lists the known names so the model can retry.
+"""
+
+import difflib
+from collections.abc import Iterable, Mapping, MutableMapping
+from typing import Any, Protocol, cast
+
+from pydantic import BaseModel, ValidationError
+
+from dndkit.errors import AlreadyExistsError, InvalidChangeError, NotFoundError
+from dndkit.text import normalize as normalize  # callers use registry.normalize
+
+
+class Spoken(Protocol):
+    """Anything with a display name."""
+
+    @property
+    def name(self) -> str: ...
+
+
+class Named(Spoken, Protocol):
+    """An entity with an ID and a display name."""
+
+    @property
+    def id(self) -> str: ...
+
+
+def known_names(entities: Iterable[Named]) -> str:
+    """Sorted names for an error message."""
+    names = sorted(entity.name for entity in entities)
+    return ", ".join(names) if names else "none yet"
+
+
+def find[E: Named](items: Mapping[str, E], ref: str, kind: str, hint: str = "") -> E:
+    """The entity whose ID or name is *ref*, or the only one whose name contains it.
+
+    Spoken names get shortened ("the lighthouse" for "The Dark Lighthouse"): a
+    part of a name (3 characters or more) is enough when no other name shares it.
+    """
+    found = find_exact(items, ref)
+    if found is not None:
+        return found
+    partial = partial_matches(items.values(), ref)
+    if len(partial) == 1:
+        return partial[0]
+    near = did_you_mean([e.name for e in items.values()], ref)
+    known = known_names(items.values())
+    raise NotFoundError(f"No {kind} named '{ref}'.{near} Known {kind}s: {known}.{hint}")
+
+
+def closest(names: Iterable[str], ref: str) -> str | None:
+    """The name *ref* reads like a slip for (a translated name, a misheard one), if
+    one is close enough. Only ever a hint: the model chooses, nothing is guessed."""
+    by_key = {normalize(name): name for name in names}
+    close = difflib.get_close_matches(normalize(ref), list(by_key), n=1, cutoff=0.75)
+    return by_key[close[0]] if close else None
+
+
+def did_you_mean(names: Iterable[str], ref: str) -> str:
+    """ " Did you mean 'Gobelin'?", or nothing."""
+    near = closest(names, ref)
+    return f" Did you mean '{near}'?" if near else ""
+
+
+def quoted(names: Iterable[str], ref: str) -> str:
+    """ "'Goblin' (did you mean 'Gobelin'?)", or "'Goblin'": an unknown name in a list."""
+    near = closest(names, ref)
+    return f"'{ref}' (did you mean '{near}'?)" if near else f"'{ref}'"
+
+
+def find_exact[E: Named](items: Mapping[str, E], ref: str) -> E | None:
+    """The entity whose ID or whole name is *ref*, or None. Creating or linking
+    goes by this: "Wolf" must not update or become the "Dire Wolf"."""
+    if ref in items:
+        return items[ref]
+    wanted = normalize(ref)
+    return next((e for e in items.values() if normalize(e.name) == wanted), None)
+
+
+def partial_matches[E: Spoken](entities: Iterable[E], ref: str) -> list[E]:
+    """The entities whose name holds *ref* (3 characters or more)."""
+    wanted = normalize(ref)
+    if len(wanted) < 3:
+        return []
+    return [e for e in entities if wanted in normalize(e.name)]
+
+
+def find_many[E: Named](
+    items: Mapping[str, E], refs: Iterable[str], kind: str, hint: str = ""
+) -> list[E]:
+    """Every entity in *refs*, or one error naming all the unknown ones."""
+    found: list[E] = []
+    missing: list[str] = []
+    for ref in refs:
+        try:
+            entity = find(items, ref, kind)
+        except NotFoundError:
+            missing.append(ref)
+            continue
+        if entity not in found:
+            found.append(entity)
+    if missing:
+        names = [e.name for e in items.values()]
+        unknown = ", ".join(quoted(names, ref) for ref in missing)
+        raise NotFoundError(
+            f"Unknown {kind}s: {unknown}. Known {kind}s: {known_names(items.values())}.{hint}"
+        )
+    return found
+
+
+def ensure_name_free(
+    items: Mapping[str, Named], name: str, kind: str, *, exclude_id: str | None = None
+) -> None:
+    """Refuse a name another entity of this kind already answers to."""
+    wanted = normalize(name)
+    if not wanted:
+        raise InvalidChangeError(f"A {kind} needs a name.")
+    for entity in items.values():
+        if entity.id != exclude_id and normalize(entity.name) == wanted:
+            raise AlreadyExistsError(
+                f"A {kind} named '{entity.name}' already exists (id {entity.id}). "
+                "Update that one, or choose another name."
+            )
+
+
+def add[E: Named](items: MutableMapping[str, E], entity: E, kind: str) -> E:
+    """Store a new entity under its ID; its name must be free."""
+    ensure_name_free(items, entity.name, kind)
+    items[entity.id] = entity
+    return entity
+
+
+def remove[E: Named](items: MutableMapping[str, E], ref: str, kind: str) -> E:
+    """Remove and return the entity *ref* names."""
+    entity = find(items, ref, kind)
+    del items[entity.id]
+    return entity
+
+
+def revised[M: BaseModel](model: M, changes: Mapping[str, Any]) -> M:
+    """A validated copy of *model* with *changes*; the original stays untouched."""
+    data = model.model_dump()
+    data.update(changes)
+    try:
+        return type(model).model_validate(data)
+    except ValidationError as exc:
+        problems = "; ".join(
+            f"{'.'.join(map(str, error['loc']))}: {error['msg']}" for error in exc.errors()
+        )
+        raise InvalidChangeError(f"Invalid change: {problems}.") from exc
+
+
+def update[E: Named](
+    items: MutableMapping[str, E],
+    ref: str,
+    kind: str,
+    changes: Mapping[str, Any],
+    *,
+    name_field: str = "name",
+) -> E:
+    """Apply *changes* to the entity *ref* names, keeping names unique."""
+    entity = find(items, ref, kind)
+    new_name = changes.get(name_field)
+    if new_name is not None:
+        ensure_name_free(items, new_name, kind, exclude_id=entity.id)
+    updated = cast(E, revised(cast(BaseModel, entity), changes))
+    items[entity.id] = updated
+    return updated

dndkit/game/resources.py

@@ -0,0 +1,96 @@
+"""What characters carry and how they hang on: items, death saves."""
+
+from typing import Literal
+
+from dndkit.errors import InvalidChangeError, NotFoundError
+from dndkit.game import characters, registry
+from dndkit.models import Campaign, Character, Item, now
+
+DeathSave = Literal["success", "failure", "nat20", "nat1", "stabilized"]
+
+
+def add_item(campaign: Campaign, ref: str, item: Item) -> tuple[Character, Item]:
+    """Give an item; one already held (same name and type) stacks."""
+    character = characters.find(campaign, ref)
+    held = _held(character, item.name)
+    if held is not None and held.item_type == item.item_type:
+        held.quantity += item.quantity
+        item = held
+    else:
+        character.inventory.append(item)
+    character.updated_at = now()
+    return character, item
+
+
+def remove_item(
+    campaign: Campaign, ref: str, item_name: str, quantity: int
+) -> tuple[Character, Item, int]:
+    """Take *quantity* of an item; returns the character, the item and what is left."""
+    character = characters.find(campaign, ref)
+    held = _held(character, item_name)
+    if held is None:
+        raise NotFoundError(
+            f"{character.name} has no '{item_name}'. "
+            f"Inventory: {registry.known_names(character.inventory)}."
+        )
+    if quantity > held.quantity:
+        raise InvalidChangeError(f"{character.name} has only {held.quantity} x {held.name}.")
+    remaining = held.quantity - quantity
+    if remaining:
+        held.quantity = remaining
+    else:
+        character.inventory = [item for item in character.inventory if item is not held]
+    character.updated_at = now()
+    return character, held, remaining
+
+
+def _held(character: Character, name: str) -> Item | None:
+    wanted = registry.normalize(name)
+    return next((i for i in character.inventory if registry.normalize(i.name) == wanted), None)
+
+
+def record_death_save(campaign: Campaign, ref: str, outcome: DeathSave) -> str:
+    """Record one death saving throw (PHB ch. 9) and say where it leaves the character."""
+    character = characters.find(campaign, ref)
+    if character.hit_points_current > 0:
+        raise InvalidChangeError(
+            f"{character.name} has {character.hit_points_current} HP; "
+            "death saves are rolled at 0 HP only."
+        )
+    if character.death_saves_failure >= 3:
+        raise InvalidChangeError(f"{character.name} is dead (3 failed death saves).")
+    if character.stable:
+        raise InvalidChangeError(
+            f"{character.name} is stable: no more death saves. They wake with 1 HP after "
+            "1d4 hours, or when healed."
+        )
+    character.updated_at = now()
+    if outcome == "stabilized":  # Spare the Dying, a Medicine check (DC 10)
+        reset_death_saves(character)
+        character.stable = True
+        return f"{character.name} is stable at 0 HP: no more death saves."
+    if outcome == "nat20":
+        character.hit_points_current = 1
+        character.conditions = [c for c in character.conditions if c != "unconscious"]
+        reset_death_saves(character)
+        return f"{character.name} rolls a natural 20, regains 1 HP and is conscious."
+    if outcome == "success":
+        character.death_saves_success += 1
+    else:
+        failures = 2 if outcome == "nat1" else 1
+        character.death_saves_failure = min(3, character.death_saves_failure + failures)
+    if character.death_saves_failure >= 3:
+        return f"{character.name} dies (3 failed death saves)."
+    if character.death_saves_success >= 3:
+        reset_death_saves(character)
+        character.stable = True
+        return f"{character.name} is stable at 0 HP: no more death saves."
+    return (
+        f"{character.name}: {character.death_saves_success} successes, "
+        f"{character.death_saves_failure} failures."
+    )
+
+
+def reset_death_saves(character: Character) -> None:
+    character.death_saves_success = 0
+    character.death_saves_failure = 0