dndkit 0.4.0__py3-none-any.whl

dndkit/game/combatants.py

@@ -0,0 +1,188 @@
+"""Turning participants into combatants: characters linked, monsters filled in."""
+
+import random
+import secrets
+from collections import Counter
+from collections.abc import Sequence
+from typing import Any
+
+from dndkit.game import bestiary, characters, dice, registry, seating
+from dndkit.game.dice import RollResult
+from dndkit.models import Campaign, Character, Combatant, Encounter, Monster, Participant
+
+_SYSTEM_RNG = secrets.SystemRandom()
+
+
+def build(campaign: Campaign, participant: Participant) -> Combatant:
+    """A combatant for *participant*.
+
+    A party character is linked to its sheet (hit points live there). A name
+    found in the bestiary takes that stat block, unless the call gives its own
+    hit points or armor class. Anyone else keeps what the call gives.
+    """
+    name = participant.name.strip()
+    character = character_for(campaign, name)
+    if character is not None:
+        return Combatant(
+            name=character.name, initiative=participant.initiative, character_id=character.id
+        )
+    monster = bestiary.monster_for(campaign, name)
+    hit_points = participant.hit_points or (monster.hit_points if monster else None)
+    armor_class = participant.armor_class
+    if armor_class is None and monster is not None:
+        armor_class = monster.armor_class
+    return Combatant(
+        name=name,
+        initiative=participant.initiative,
+        monster=monster.name if monster else None,
+        hit_points=hit_points,
+        hit_points_max=hit_points,
+        armor_class=armor_class,
+        xp=monster.xp if monster else 0,
+        size=monster.size if monster else "medium",
+        speed=bestiary.walking_speed(monster) if monster else None,
+        **(legendary(monster) if monster else {}),
+    )
+
+
+def legendary(monster: Monster) -> dict[str, Any]:
+    """A combatant's boss fields from its stat block, its legendary uses full."""
+    return {
+        "boss": monster.boss,
+        "legendary_actions": monster.legendary_actions,
+        "legendary_actions_left": monster.legendary_actions,
+        "legendary_resistances_left": monster.legendary_resistances,
+    }
+
+
+def character_for(campaign: Campaign, name: str) -> Character | None:
+    """The party character a combatant name stands for: its name, whole words of it
+    ("Aria" for "Aria Moonwhisper"), or a name that holds it ("Fizbin the gnome").
+    A part of a word is not enough: a "Wolf" is not "Wolfgang"."""
+    found = registry.find_exact(campaign.characters, name)
+    if found is not None:
+        return found
+    words = f" {registry.normalize(name)} "
+    holding = [
+        c
+        for c in campaign.characters.values()
+        if f" {registry.normalize(c.name)} " in words or words in f" {registry.normalize(c.name)} "
+    ]
+    return holding[0] if len(holding) == 1 else None
+
+
+def refresh(campaign: Campaign) -> list[str]:
+    """Bring the running fight up to date with the sheets and the bestiary.
+
+    A combatant named after a party character but not linked to its sheet is
+    linked (its hit points, conditions and speed then come from the sheet); a
+    monster fighting without hit points takes its stat block's, once saved.
+    Returns a line per combatant changed.
+    """
+    lines: list[str] = []
+    order = campaign.game_state.initiative_order
+    linked = {c.character_id for c in order if c.character_id}
+    for combatant in order:
+        if combatant.character_id is not None:
+            continue
+        character = character_for(campaign, combatant.name)
+        if character is not None and character.id not in linked:
+            combatant.character_id, combatant.hit_points, combatant.hit_points_max = (
+                character.id,
+                None,
+                None,
+            )
+            linked.add(character.id)
+            lines.append(f"{combatant.name} now plays from {character.name}'s sheet.")
+            continue
+        monster = bestiary.monster_for(campaign, combatant.name)
+        if monster is not None and combatant.hit_points is None:
+            _take_stats(combatant, monster)
+            lines.append(
+                f"{combatant.name} takes the {monster.name} stat block: "
+                f"HP {monster.hit_points}, AC {combatant.armor_class}."
+            )
+    return lines
+
+
+def _take_stats(combatant: Combatant, monster: Monster) -> None:
+    combatant.monster = monster.name
+    combatant.hit_points = combatant.hit_points_max = monster.hit_points
+    if combatant.armor_class is None:
+        combatant.armor_class = monster.armor_class
+    if combatant.speed is None:
+        combatant.speed = bestiary.walking_speed(monster)
+    combatant.xp = monster.xp
+    combatant.size = monster.size
+    for field, value in legendary(monster).items():
+        setattr(combatant, field, value)
+
+
+def from_encounter(
+    campaign: Campaign, encounter: Encounter, rng: random.Random | None = None
+) -> list[Combatant]:
+    """The encounter's monsters, each with initiative rolled (d20 + bonus)."""
+    rng = rng or _SYSTEM_RNG
+    combatants: list[Combatant] = []
+    for group in encounter.monsters:
+        monster = bestiary.find_monster(campaign, group.monster)
+        for number in range(group.count):
+            combatants.append(
+                Combatant(
+                    name=monster.name,
+                    initiative=rng.randint(1, 20) + monster.initiative_bonus,
+                    monster=monster.name,
+                    hit_points=monster.hit_points,
+                    hit_points_max=monster.hit_points,
+                    armor_class=monster.armor_class,
+                    xp=monster.xp,
+                    size=monster.size,
+                    speed=bestiary.walking_speed(monster),
+                    position=group.at[number].upper() if number < len(group.at) else None,
+                    hidden=group.hidden,
+                    **legendary(monster),
+                )
+            )
+    return combatants
+
+
+def party_at_the_table(campaign: Campaign) -> list[tuple[Combatant, RollResult]]:
+    """The characters at the table, each with initiative rolled (d20 + Dexterity):
+    for a fight started with its foes only."""
+    joined: list[tuple[Combatant, RollResult]] = []
+    for character in seating.present_characters(campaign):
+        bonus = characters.initiative(character)
+        result = dice.roll(f"d20{bonus:+d}" if bonus else "d20")
+        fighter = Combatant(
+            name=character.name, initiative=result.total, character_id=character.id
+        )
+        joined.append((fighter, result))
+    return joined
+
+
+def number_duplicates(order: Sequence[Combatant]) -> list[Combatant]:
+    """Same-named combatants become "Goblin 1", "Goblin 2"... so they can be told apart."""
+    totals = Counter(registry.normalize(c.name) for c in order)
+    taken = set(totals)
+    seen: Counter[str] = Counter()
+    numbered: list[Combatant] = []
+    for combatant in order:
+        key = registry.normalize(combatant.name)
+        if totals[key] > 1 and combatant.character_id is None:
+            seen[key] += 1
+            while f"{key} {seen[key]}" in taken:  # a "Goblin 1" given by name
+                seen[key] += 1
+            combatant = combatant.model_copy(update={"name": f"{combatant.name} {seen[key]}"})
+        numbered.append(combatant)
+    return numbered
+
+
+def unique_name(taken: Sequence[Combatant], name: str) -> str:
+    """*name*, or the next free "name N" when the fight already has one."""
+    names = {registry.normalize(c.name) for c in taken}
+    if registry.normalize(name) not in names and registry.normalize(f"{name} 1") not in names:
+        return name
+    number = 2
+    while registry.normalize(f"{name} {number}") in names:
+        number += 1
+    return f"{name} {number}"

dndkit/game/concentration.py

@@ -0,0 +1,43 @@
+"""Concentration (PHB ch. 10): one spell held at a time, a Constitution save
+when hurt (DC 10 or half the damage), lost when incapacitated or at 0 hit points."""
+
+from dndkit.game import proficiencies
+from dndkit.models import Character, Combatant
+from dndkit.text import normalize
+
+INCAPACITATING = frozenset({"incapacitated", "paralyzed", "petrified", "stunned", "unconscious"})
+
+Holder = Character | Combatant
+
+
+def concentrate(holder: Holder, name: str, spell: str | None) -> str:
+    """Hold *spell*, letting go of any other; without one, stop concentrating."""
+    before = holder.concentration
+    spell = spell.strip() if spell else None
+    holder.concentration = spell or None
+    if spell:
+        same = before is not None and normalize(before) == normalize(spell)
+        ended = f" ({before} ends)" if before and not same else ""
+        return f"{name} concentrates on {spell}{ended}."
+    return f"{name} stops concentrating on {before}." if before else f"{name} held no spell."
+
+
+def after_damage(holder: Holder, name: str, damage: int, down: bool) -> str | None:
+    """The save a hurt creature makes to keep its spell, or the spell lost at 0 HP."""
+    if not holder.concentration:
+        return None
+    if down or INCAPACITATING & set(holder.conditions):
+        return lose(holder, name)
+    bonus = ""
+    if isinstance(holder, Character):
+        bonus = f", CON save {proficiencies.save_bonus(holder, 'constitution'):+d}"
+    return (
+        f"{name} is concentrating on {holder.concentration}: Constitution save DC "
+        f"{max(10, damage // 2)}{bonus}. If it fails, set_concentration without a spell."
+    )
+
+
+def lose(holder: Holder, name: str) -> str | None:
+    """Let go of the spell held, if any: incapacitated, down, or dead."""
+    spell, holder.concentration = holder.concentration, None
+    return f"{name} loses concentration on {spell}." if spell else None

dndkit/game/dice.py

@@ -0,0 +1,186 @@
+"""Dice notation: parse "2d6+1d4+3" or "d20 - 1" and roll it."""
+
+import itertools
+import random
+import re
+import secrets
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from dndkit.errors import DiceError
+
+MAX_DICE = 100
+MAX_SIDES = 1000
+MAX_CONSTANT = 1000
+_EXAMPLES = "Use forms like d20, 1d20+5, 2d6+1d4+3 or 4d6-1."
+_TERM = re.compile(r"\s*([+-])?\s*(?:(\d*)\s*d\s*(\d+)|(\d+))\s*", re.IGNORECASE)
+_SYSTEM_RNG = secrets.SystemRandom()
+
+
+@dataclass(frozen=True)
+class DiceTerm:
+    """``count`` dice of ``sides`` faces, or a constant when ``sides`` is 0."""
+
+    sign: int
+    count: int
+    sides: int
+
+
+@dataclass(frozen=True)
+class RolledTerm:
+    """One term as rolled: every die's face, or the constant (``sides`` 0).
+
+    With advantage or disadvantage the term holds both d20 and ``kept`` says
+    which value counts.
+    """
+
+    sign: int
+    sides: int
+    faces: tuple[int, ...]
+    kept: int | None = None
+
+    @property
+    def value(self) -> int:
+        """What the term adds to the total, before its sign."""
+        return self.kept if self.kept is not None else sum(self.faces)
+
+
+@dataclass(frozen=True)
+class RollResult:
+    """What was rolled: the line to read out, and every die for an animation."""
+
+    notation: str
+    total: int
+    detail: str
+    mode: str  # normal, advantage, disadvantage
+    terms: tuple[RolledTerm, ...]
+
+
+def parse(notation: str) -> list[DiceTerm]:
+    """The terms of *notation*; raises ``DiceError`` on anything else."""
+    text = notation.strip()
+    terms: list[DiceTerm] = []
+    position = 0
+    while position < len(text):
+        match = _TERM.match(text, position)
+        if match is None or match.end() == position or (terms and match.group(1) is None):
+            raise DiceError(f"Invalid dice notation '{notation}'. {_EXAMPLES}")
+        terms.append(_term(match, notation))
+        position = match.end()
+    if not any(term.sides for term in terms):
+        raise DiceError(f"'{notation}' has no dice. {_EXAMPLES}")
+    if sum(term.count for term in terms if term.sides) > MAX_DICE:
+        raise DiceError(f"'{notation}' rolls more than {MAX_DICE} dice.")
+    return terms
+
+
+def _term(match: re.Match[str], notation: str) -> DiceTerm:
+    sign = -1 if match.group(1) == "-" else 1
+    if match.group(4) is not None:
+        constant = int(match.group(4))
+        if constant > MAX_CONSTANT:
+            raise DiceError(f"'{notation}': modifiers go up to {MAX_CONSTANT}.")
+        return DiceTerm(sign, constant, 0)
+    count = int(match.group(2) or 1)
+    sides = int(match.group(3))
+    if not 1 <= count <= MAX_DICE:
+        raise DiceError(f"'{notation}': roll between 1 and {MAX_DICE} dice.")
+    if not 2 <= sides <= MAX_SIDES:
+        raise DiceError(f"'{notation}': dice have between 2 and {MAX_SIDES} sides.")
+    return DiceTerm(sign, count, sides)
+
+
+def roll(
+    notation: str,
+    *,
+    advantage: bool = False,
+    disadvantage: bool = False,
+    rng: random.Random | None = None,
+) -> RollResult:
+    """Roll *notation*; advantage and disadvantage apply to a single d20."""
+    terms = parse(notation)
+    rng = rng or _SYSTEM_RNG
+    mode = _mode(terms, notation, advantage, disadvantage)
+    rolled = tuple(_roll_term(term, rng, mode) for term in terms)
+    total = sum(term.sign * term.value for term in rolled)
+    parts: list[str] = []
+    for term in rolled:
+        shown = _describe(term, mode)
+        sign = "-" if term.sign < 0 else "+"
+        parts.append(f"{sign} {shown}" if parts or term.sign < 0 else shown)
+    detail = " ".join(parts)
+    if advantage and disadvantage:
+        detail += " (advantage and disadvantage cancel out)"
+    return RollResult(
+        notation=notation.strip(),
+        total=total,
+        detail=f"{detail} = {total}",
+        mode=mode,
+        terms=rolled,
+    )
+
+
+def _mode(terms: list[DiceTerm], notation: str, advantage: bool, disadvantage: bool) -> str:
+    if advantage == disadvantage:
+        return "normal"
+    dice = [term for term in terms if term.sides]
+    if len(dice) != 1 or dice[0].count != 1 or dice[0].sides != 20:
+        raise DiceError(f"Advantage and disadvantage apply to one d20, not '{notation}'.")
+    return "advantage" if advantage else "disadvantage"
+
+
+def _roll_term(term: DiceTerm, rng: random.Random, mode: str) -> RolledTerm:
+    if not term.sides:
+        return RolledTerm(term.sign, 0, (term.count,))
+    if mode != "normal":
+        faces = (rng.randint(1, 20), rng.randint(1, 20))
+        kept = max(faces) if mode == "advantage" else min(faces)
+        return RolledTerm(term.sign, 20, faces, kept)
+    return RolledTerm(
+        term.sign, term.sides, tuple(rng.randint(1, term.sides) for _ in range(term.count))
+    )
+
+
+def _describe(term: RolledTerm, mode: str) -> str:
+    if not term.sides:
+        return str(term.faces[0])
+    if term.kept is not None:
+        return f"d20 {mode} [{term.faces[0]}, {term.faces[1]}] keeps {term.kept}"
+    return f"{len(term.faces)}d{term.sides} [{', '.join(map(str, term.faces))}]"
+
+
+@dataclass(frozen=True)
+class LoggedRoll:
+    """A roll in the log: its sequence number, when (unix time), and whether only
+    the game master may see it."""
+
+    number: int
+    at: float
+    result: RollResult
+    secret: bool = False
+
+
+class DiceLog:
+    """The last rolls of this session, for the dice app to show; never saved."""
+
+    def __init__(self, size: int = 20, on_record: Callable[[], None] | None = None) -> None:
+        self._rolls: deque[LoggedRoll] = deque(maxlen=size)
+        self._counter = itertools.count(1)
+        self._lock = threading.Lock()
+        self._on_record = on_record or (lambda: None)
+
+    def record(self, result: RollResult, secret: bool = False) -> int:
+        """Keep *result*; returns its sequence number."""
+        with self._lock:
+            number = next(self._counter)
+            self._rolls.append(LoggedRoll(number, time.time(), result, secret))
+        self._on_record()
+        return number
+
+    def recent(self) -> list[LoggedRoll]:
+        """The rolls kept, oldest first."""
+        with self._lock:
+            return list(self._rolls)

dndkit/game/effects.py

@@ -0,0 +1,183 @@
+"""Hit points and conditions for anyone at the table: characters or combatants.
+
+A whole name is looked up in the running fight first, then among the party;
+only then a part of a name, if it points to one target alone. A combatant
+linked to a character is changed on the character's sheet; any other
+combatant keeps its own hit points and conditions, and leaves the initiative
+order when it drops to 0 HP. Each change first brings the fight up
+to date (``combatants.refresh``): a sheet created or a stat block saved after
+the fight began takes effect at once.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from dndkit.errors import InvalidChangeError, NotFoundError
+from dndkit.game import characters, combat, combatants, concentration, registry, rules
+from dndkit.game.concentration import INCAPACITATING
+from dndkit.models import CONDITIONS, Campaign, Character, Combatant, now
+
+
+@dataclass(frozen=True)
+class Target:
+    """One resolved name: a party character, or a combatant with its own stats."""
+
+    name: str
+    character: Character | None = None
+    combatant: Combatant | None = None
+
+
+def resolve(campaign: Campaign, refs: Sequence[str]) -> list[Target]:
+    """Every target in *refs*, once each, or one error naming all the unknown ones."""
+    state = campaign.game_state
+    fighters = state.initiative_order if state.in_combat else []
+    targets: list[Target] = []
+    missing: list[str] = []
+    for ref in refs:
+        target = _target(campaign, fighters, ref)
+        if target is None:
+            missing.append(ref)
+        elif all(t.name != target.name for t in targets):
+            targets.append(target)
+    if missing:
+        known = [c.name for c in fighters] + [c.name for c in campaign.characters.values()]
+        unknown = ", ".join(registry.quoted(known, ref) for ref in missing)
+        raise NotFoundError(f"Unknown: {unknown}. Known: {', '.join(sorted(set(known)))}.")
+    return targets
+
+
+def _target(campaign: Campaign, fighters: Sequence[Combatant], ref: str) -> Target | None:
+    """A whole name, a fighter's then a character's; else the only one a part names.
+    "Thorn" is the character Thorn, not the "Thornback Boar"."""
+    wanted = registry.normalize(ref)
+    fighter = next((c for c in fighters if registry.normalize(c.name) == wanted), None)
+    if fighter is not None:
+        return _fighting(campaign, fighter)
+    character = registry.find_exact(campaign.characters, ref)
+    if character is not None:
+        return Target(character.name, character=character)
+    in_fight = registry.partial_matches(fighters, ref)
+    linked = {c.character_id for c in in_fight}
+    sheets = registry.partial_matches(campaign.characters.values(), ref)
+    sheets = [c for c in sheets if c.id not in linked]
+    if len(in_fight) + len(sheets) != 1:
+        return None
+    return _fighting(campaign, in_fight[0]) if in_fight else Target(sheets[0].name, sheets[0])
+
+
+def _fighting(campaign: Campaign, fighter: Combatant) -> Target | None:
+    """A fighter as a target: its sheet when it is a party character."""
+    if fighter.character_id is None:
+        return Target(fighter.name, combatant=fighter)
+    character = campaign.characters.get(fighter.character_id)
+    return Target(character.name, character=character) if character else None
+
+
+def change_hit_points(campaign: Campaign, refs: Sequence[str], amount: int) -> list[str]:
+    """Damage (negative) or heal (positive) each target; one line per target."""
+    lines = combatants.refresh(campaign)
+    for target in resolve(campaign, refs):
+        holder: Character | Combatant
+        if target.character is not None:
+            holder = target.character
+            lines.append(characters.change_hp(holder, amount))
+            down = holder.hit_points_current == 0
+        elif target.combatant is not None:
+            holder = target.combatant
+            lines.append(_change_combatant_hp(campaign, holder, amount))
+            down = not holder.hit_points
+        else:
+            continue
+        if amount < 0 and (held := concentration.after_damage(holder, target.name, -amount, down)):
+            lines.append(held)
+    return lines
+
+
+def _change_combatant_hp(campaign: Campaign, combatant: Combatant, amount: int) -> str:
+    if combatant.hit_points is None:
+        raise InvalidChangeError(
+            f"{combatant.name}'s hit points are not tracked: save its stat block with "
+            "save_monster (it then fights with it), then change its hit points again."
+        )
+    maximum = combatant.hit_points_max or combatant.hit_points
+    hp = rules.apply_hp_change(combatant.hit_points, maximum, 0, amount)
+    combatant.hit_points = hp.current
+    if hp.current > 0:
+        return f"{combatant.name}: HP {hp.current}/{maximum}"
+    _, acting = combat.remove(campaign.game_state, combatant.name)
+    after = f" {acting.name} acts now." if acting else " No one is left: call end_combat."
+    return f"{combatant.name} drops to 0 HP and leaves the fight.{after}"
+
+
+def grant_temporary_hp(campaign: Campaign, refs: Sequence[str], amount: int) -> list[str]:
+    """Temporary hit points don't stack: each character keeps the higher value."""
+    lines = combatants.refresh(campaign)
+    for target in resolve(campaign, refs):
+        if target.character is None:
+            raise InvalidChangeError("Temporary hit points are tracked for characters only.")
+        character = target.character
+        character.temporary_hit_points = max(character.temporary_hit_points, amount)
+        character.updated_at = now()
+        lines.append(f"{character.name}: {character.temporary_hit_points} temporary HP")
+    return lines
+
+
+def set_condition(
+    campaign: Campaign,
+    refs: Sequence[str],
+    condition: str,
+    active: bool,
+    rounds: int | None = None,
+) -> list[str]:
+    """Add or remove one condition on each target; one line per target. *rounds*:
+    it ends by itself at the end of the target's turn that many turns on."""
+    if condition not in CONDITIONS:
+        raise InvalidChangeError(
+            f"Unknown condition '{condition}'. Conditions: {', '.join(CONDITIONS)}."
+        )
+    lines = combatants.refresh(campaign)
+    for target in resolve(campaign, refs):
+        holder = target.character or target.combatant
+        if holder is None:
+            continue
+        others = [c for c in holder.conditions if c != condition]
+        holder.conditions = [*others, condition] if active else others
+        timers = {c: n for c, n in holder.condition_rounds.items() if c != condition}
+        holder.condition_rounds = {**timers, condition: rounds} if active and rounds else timers
+        lines.append(f"{target.name}: {timed(holder) or 'no condition'}")
+        if (
+            active
+            and condition in INCAPACITATING
+            and (lost := concentration.lose(holder, target.name))
+        ):
+            lines.append(lost)
+    return lines
+
+
+def end_of_turn(campaign: Campaign, combatant: Combatant) -> list[str]:
+    """Count down the timed conditions of the creature whose turn ends."""
+    holder = campaign.characters.get(combatant.character_id or "") or combatant
+    left = {c: n - 1 for c, n in holder.condition_rounds.items() if c in holder.conditions}
+    ended = [c for c, n in left.items() if n <= 0]
+    holder.condition_rounds = {c: n for c, n in left.items() if n > 0}
+    holder.conditions = [c for c in holder.conditions if c not in ended]
+    return [f"{combatant.name}: {', '.join(ended)} ends."] if ended else []
+
+
+def timed(holder: Character | Combatant) -> str:
+    """ "stunned (1 turn left), prone": each condition, with what remains of a timed one."""
+    rounds = holder.condition_rounds
+    return ", ".join(
+        f"{c} ({rounds[c]} turn{'s' if rounds[c] > 1 else ''} left)" if c in rounds else c
+        for c in holder.conditions
+    )
+
+
+def set_concentration(campaign: Campaign, ref: str, spell: str | None) -> str:
+    """Start or stop concentrating, for a character or a combatant."""
+    combatants.refresh(campaign)
+    (target,) = resolve(campaign, [ref])
+    holder = target.character or target.combatant
+    if holder is None:
+        raise NotFoundError(f"Unknown: '{ref}'.")
+    return concentration.concentrate(holder, target.name, spell)

dndkit/game/grid.py

@@ -0,0 +1,88 @@
+"""Squares on a battle map: names like "D7", areas, footprints and distances.
+
+Columns are letters from A, rows numbers from 1, A1 at the top left. Every
+square is 5 feet and, as in the Player's Handbook ("Playing on a Grid"), a
+diagonal step costs 5 feet like any other, so two squares are as many steps
+apart as the larger of their column and row differences.
+"""
+
+import re
+
+from dndkit.errors import InvalidChangeError
+from dndkit.models import Battlefield, Size
+
+FEET = 5
+Square = tuple[int, int]  # column, row; both from 0
+
+# Squares a side: Tiny and Small creatures still hold a whole square here.
+SIZE_SQUARES: dict[str, int] = {
+    "tiny": 1,
+    "small": 1,
+    "medium": 1,
+    "large": 2,
+    "huge": 3,
+    "gargantuan": 4,
+}
+SIZE_RANK: dict[str, int] = {size: rank for rank, size in enumerate(SIZE_SQUARES)}
+
+_NAME = re.compile(r"([A-Za-z])\s*(\d{1,2})")
+
+
+def name(square: Square) -> str:
+    """ "D7" for (3, 6)."""
+    column, row = square
+    return f"{chr(ord('A') + column)}{row + 1}"
+
+
+def parse(text: str, field: Battlefield) -> Square:
+    """The square *text* names ("d7", "D 7"), checked against the map's edges."""
+    match = _NAME.fullmatch(text.strip())
+    if match is None:
+        raise InvalidChangeError(f"'{text}' is not a square: write a column letter and a row, D7.")
+    square = (ord(match.group(1).upper()) - ord("A"), int(match.group(2)) - 1)
+    if not inside(square, field):
+        last = name((field.width - 1, field.height - 1))
+        raise InvalidChangeError(f"{name(square)} is off the map, which runs from A1 to {last}.")
+    return square
+
+
+def area(text: str, field: Battlefield) -> list[Square]:
+    """The squares *text* names: one ("C3") or a rectangle between two corners ("C1:E2")."""
+    corners = [parse(part, field) for part in text.split(":")]
+    if len(corners) > 2:
+        raise InvalidChangeError(f"'{text}' has more than two corners.")
+    (x1, y1), (x2, y2) = corners[0], corners[-1]
+    return [
+        (x, y)
+        for y in range(min(y1, y2), max(y1, y2) + 1)
+        for x in range(min(x1, x2), max(x1, x2) + 1)
+    ]
+
+
+def inside(square: Square, field: Battlefield) -> bool:
+    """Whether *square* is on the map."""
+    column, row = square
+    return 0 <= column < field.width and 0 <= row < field.height
+
+
+def footprint(top_left: Square, size: Size) -> list[Square]:
+    """The squares a creature of *size* holds from *top_left*."""
+    side = SIZE_SQUARES[size]
+    x, y = top_left
+    return [(x + dx, y + dy) for dy in range(side) for dx in range(side)]
+
+
+def steps_between(a: list[Square], b: list[Square]) -> int:
+    """Steps between the nearest squares of two footprints: 1 when adjacent, 0 when they meet."""
+    dx = max(
+        0, min(x for x, _ in b) - max(x for x, _ in a), min(x for x, _ in a) - max(x for x, _ in b)
+    )
+    dy = max(
+        0, min(y for _, y in b) - max(y for _, y in a), min(y for _, y in a) - max(y for _, y in b)
+    )
+    return max(dx, dy)
+
+
+def feet_between(a: list[Square], b: list[Square]) -> int:
+    """Distance in feet between two footprints, as 5e measures it on a grid."""
+    return steps_between(a, b) * FEET