dndkit 0.4.0__py3-none-any.whl

dndkit/game/rests.py

@@ -0,0 +1,98 @@
+"""Short and long rests (PHB ch. 8), and the Hit Dice spent and regained."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import characters, dice, registry, rules
+from dndkit.game.dice import RollResult
+from dndkit.game.resources import reset_death_saves
+from dndkit.models import Campaign, Character, now
+
+RestKind = Literal["short", "long"]
+
+
+@dataclass(frozen=True)
+class Rested:
+    """What a rest did: a line per character, and the Hit Dice rolled."""
+
+    lines: list[str]
+    rolls: list[RollResult]
+
+
+def rest(campaign: Campaign, refs: Sequence[str], kind: RestKind, hit_dice: int = 0) -> Rested:
+    """A rest for the named characters, or everyone when *refs* is empty. On a short
+    rest each spends *hit_dice* Hit Dice to heal."""
+    if hit_dice and kind == "long":
+        raise InvalidChangeError("Hit Dice are spent on a short rest; a long rest heals fully.")
+    targets = (
+        registry.find_many(campaign.characters, refs, characters.KIND)
+        if refs
+        else list(campaign.characters.values())
+    )
+    if kind == "long":
+        return Rested([_long_rest(c) for c in targets], [])
+    spent = [_spend(c, hit_dice) for c in targets] if hit_dice else []
+    lines = [line for line, _ in spent] or [_short_rest(c) for c in targets]
+    if spent:
+        lines += [line for c in targets if (line := _pact_slots(c))]
+    return Rested(lines, [roll for _, roll in spent])
+
+
+def _long_rest(character: Character) -> str:
+    """Needs at least 1 HP when the rest starts; half the Hit Dice come back."""
+    if character.hit_points_current == 0:
+        return f"{character.name} is at 0 HP and gains nothing from the rest"
+    cls = character.character_class
+    left = characters.hit_dice_left(character)
+    regained = min(cls.level - left, max(1, cls.level // 2))
+    character.hit_dice_remaining = f"{left + regained}d{rules.hit_die(cls.name)}"
+    character.exhaustion = max(0, character.exhaustion - 1)  # first: it may lift the halving
+    character.hit_points_current = character.hp_maximum
+    character.temporary_hit_points = 0
+    character.spell_slots_used = {}
+    reset_death_saves(character)
+    character.updated_at = now()
+    exhaustion = f", exhaustion {character.exhaustion}" if character.exhaustion else ""
+    return (
+        f"{character.name}: HP {character.hp_maximum}, spell slots restored, "
+        f"Hit Dice {character.hit_dice_remaining}{exhaustion}"
+    )
+
+
+def _short_rest(character: Character) -> str:
+    """Warlocks get their pact slots back; anyone may spend Hit Dice."""
+    pact = _pact_slots(character)
+    left = f"may spend Hit Dice to heal ({character.hit_dice_remaining} left: rest with hit_dice)"
+    return f"{pact}; {left}" if pact else f"{character.name}: {left}"
+
+
+def _pact_slots(character: Character) -> str | None:
+    if rules.class_key(character.character_class.name) != "warlock":
+        return None
+    character.spell_slots_used = {}
+    character.updated_at = now()
+    return f"{character.name}: pact slots restored"
+
+
+def _spend(character: Character, count: int) -> tuple[str, RollResult]:
+    """Roll *count* Hit Dice; each heals its roll plus the Constitution modifier."""
+    left = characters.hit_dice_left(character)
+    if count > left:
+        raise InvalidChangeError(f"{character.name} has {left} Hit Dice left.")
+    die = rules.hit_die(character.character_class.name)
+    con = character.abilities["constitution"].mod if "constitution" in character.abilities else 0
+    result = dice.roll(f"{count}d{die}")
+    healed = sum(max(0, face + con) for face in result.terms[0].faces)
+    character.hit_dice_remaining = f"{left - count}d{die}"
+    status = (
+        characters.change_hp(character, healed)
+        if healed
+        else f"{character.name}: HP {character.hit_points_current}/{character.hp_maximum}"
+    )
+    return (
+        f"{status}; spent {count}d{die} {list(result.terms[0].faces)} with CON {con:+d}: "
+        f"+{healed} HP, {left - count} Hit Dice left",
+        result,
+    )

dndkit/game/rules.py

@@ -0,0 +1,196 @@
+"""D&D 5e rules the tools apply: hit points, experience, levels, encounters."""
+
+from dataclasses import dataclass
+
+from dndkit.game.tables import (
+    CASTING_ABILITY,
+    CLASS_ALIASES,
+    CLASS_SAVES,
+    CLASSES,
+    DIFFICULTY_THRESHOLDS,
+    ENCOUNTER_MULTIPLIERS,
+    FULL_CASTER_SLOTS,
+    MONSTER_STATS,
+    PACT_SLOTS,
+    SLOW_RACES,
+    XP_BY_CHALLENGE,
+    XP_FOR_LEVEL,
+)
+from dndkit.models import ABILITIES
+from dndkit.text import normalize
+
+_FRENCH_ABILITIES = {"for": "strength", "sag": "wisdom"}
+
+
+@dataclass(frozen=True)
+class HitPoints:
+    """Hit points after a change."""
+
+    current: int
+    temporary: int
+
+
+def apply_hp_change(current: int, maximum: int, temporary: int, delta: int) -> HitPoints:
+    """Healing up to the maximum, or damage taken from temporary hit points first.
+
+    Healing never restores temporary hit points (PHB, "Temporary Hit Points").
+    """
+    if delta >= 0:
+        return HitPoints(current=min(maximum, current + delta), temporary=temporary)
+    damage = -delta
+    absorbed = min(temporary, damage)
+    return HitPoints(current=max(0, current - (damage - absorbed)), temporary=temporary - absorbed)
+
+
+def experience_per_character(total_xp: int, party_size: int) -> int:
+    """XP each character earns: the monsters' total XP split evenly (DMG, ch. 3).
+
+    The DMG's encounter multipliers rate an encounter's difficulty; they never
+    change the XP awarded.
+    """
+    if party_size < 1:
+        raise ValueError("party_size must be at least 1")
+    return total_xp // party_size
+
+
+def base_speed(race: str) -> int:
+    """Walking speed for a race: 25 for dwarves, halflings and gnomes, else 30."""
+    words = set(normalize(race).split())
+    return 25 if words & SLOW_RACES else 30
+
+
+def class_key(class_name: str) -> str | None:
+    """The 5e class a name refers to ("Magicien" -> "wizard"), or None if homebrew."""
+    name = normalize(class_name)
+    key = CLASS_ALIASES.get(name, name)
+    return key if key in CLASSES else None
+
+
+def hit_die(class_name: str) -> int:
+    """The class's hit die size; d8 for a class the rules do not know."""
+    key = class_key(class_name)
+    return CLASSES[key][0] if key else 8
+
+
+def proficiency_bonus(level: int) -> int:
+    """+2 at levels 1-4, up to +6 at 17-20."""
+    return 2 + (max(1, level) - 1) // 4
+
+
+def level_for_xp(xp: int) -> int:
+    """The highest level *xp* experience points reach."""
+    return max(level for level, needed in XP_FOR_LEVEL.items() if xp >= needed)
+
+
+def challenge_key(challenge: str) -> str:
+    """A challenge rating as the tables write it ("0.25" -> "1/4")."""
+    text = challenge.strip().replace(",", ".")
+    return {"0.125": "1/8", "0.25": "1/4", "0.5": "1/2"}.get(text, text)
+
+
+def xp_for_challenge(challenge: str) -> int | None:
+    """Monster XP for a challenge rating ("1/4", "0.25", "3"), None if unknown."""
+    return XP_BY_CHALLENGE.get(challenge_key(challenge))
+
+
+@dataclass(frozen=True)
+class MonsterStats:
+    """What a monster of some challenge rating should have (DMG ch. 9)."""
+
+    armor_class: int
+    hit_points: int
+    attack_bonus: int
+    damage_per_round: int
+    save_dc: int
+
+
+def monster_stats(challenge: str) -> MonsterStats | None:
+    """The DMG's statistics for a challenge rating, the middle of each range; None if unknown."""
+    row = MONSTER_STATS.get(challenge_key(challenge))
+    if row is None:
+        return None
+    armor, (low_hp, high_hp), attack, (low_damage, high_damage), save = row
+    return MonsterStats(
+        armor, (low_hp + high_hp) // 2, attack, (low_damage + high_damage) // 2, save
+    )
+
+
+def starting_hit_points(class_name: str, level: int, constitution_mod: int) -> int:
+    """Hit points by the PHB: the whole hit die at level 1, then its average; CON each level."""
+    die = hit_die(class_name)
+    return max(1, die + constitution_mod + (level - 1) * (die // 2 + 1 + constitution_mod))
+
+
+def casting_ability(class_name: str) -> str | None:
+    """The ability a class casts with ("Magicien" -> "intelligence"); None for non-casters."""
+    key = class_key(class_name)
+    return CASTING_ABILITY.get(key) if key else None
+
+
+def spell_slots_for(class_name: str, level: int) -> dict[int, int] | None:
+    """Spell slots by slot level for a single-class character; None for non-casters."""
+    key = class_key(class_name)
+    progression = CLASSES[key][1] if key else "none"
+    if progression == "full":
+        return dict(enumerate(FULL_CASTER_SLOTS[level], start=1))
+    if progression in ("half", "half_up"):
+        if progression == "half" and level < 2:
+            return {}
+        return dict(enumerate(FULL_CASTER_SLOTS[(level + 1) // 2], start=1))
+    if progression == "pact":
+        count, slot_level = PACT_SLOTS[level]
+        return {slot_level: count}
+    return None
+
+
+@dataclass(frozen=True)
+class Difficulty:
+    """An encounter rated against a party (DMG ch. 3, "Creating a Combat Encounter")."""
+
+    total_xp: int
+    multiplier: float
+    adjusted_xp: int
+    thresholds: tuple[int, int, int, int]  # easy, medium, hard, deadly for the party
+    rating: str  # trivial, easy, medium, hard, deadly
+
+
+def encounter_difficulty(party_levels: list[int], monster_xps: list[int]) -> Difficulty:
+    """Rate monsters against a party: XP times a count multiplier, against thresholds."""
+    if not party_levels:
+        raise ValueError("the party has no characters")
+    per_level = [DIFFICULTY_THRESHOLDS[min(20, max(1, level))] for level in party_levels]
+    easy, medium, hard, deadly = (sum(row[i] for row in per_level) for i in range(4))
+    step = _multiplier_step(len(monster_xps))
+    if len(party_levels) < 3:
+        step += 1
+    elif len(party_levels) >= 6:
+        step -= 1
+    multiplier = ENCOUNTER_MULTIPLIERS[max(0, min(step, len(ENCOUNTER_MULTIPLIERS) - 1))]
+    total = sum(monster_xps)
+    adjusted = int(total * multiplier) if monster_xps else 0
+    ratings = ((deadly, "deadly"), (hard, "hard"), (medium, "medium"), (easy, "easy"))
+    rating = next((name for limit, name in ratings if adjusted >= limit), "trivial")
+    return Difficulty(total, multiplier, adjusted, (easy, medium, hard, deadly), rating)
+
+
+def _multiplier_step(monsters: int) -> int:
+    """Index into ENCOUNTER_MULTIPLIERS for a monster count, before party size."""
+    for step, upper in enumerate((0, 1, 2, 6, 10, 14)):
+        if monsters <= upper:
+            return step
+    return 6
+
+
+def ability_name(text: str | None) -> str | None:
+    """ "INT", "Intelligence" or French "Sagesse" -> the ability's name."""
+    if not text:
+        return None
+    wanted = normalize(text)[:3]
+    found = next((a for a in ABILITIES if a.startswith(wanted)), None)
+    return found or _FRENCH_ABILITIES.get(wanted)
+
+
+def class_saves(class_name: str) -> list[str]:
+    """The saving throws a class is proficient in; none for a class the rules do not know."""
+    key = class_key(class_name)
+    return list(CLASS_SAVES[key]) if key else []

dndkit/game/seating.py

@@ -0,0 +1,71 @@
+"""Who sits at the table tonight, and which character each plays.
+
+A player is a person, named as the voice client names their voice: roomkit-ui
+opens each spoken turn with the speaker's name. A character's
+``player_name`` ties it to its player. The roll call (``seat``) says who is
+present; until there is one, the whole party counts as present.
+"""
+
+from dndkit.errors import InvalidChangeError, NotFoundError
+from dndkit.game import characters
+from dndkit.models import Campaign, Character, now
+from dndkit.text import normalize
+
+
+def same_person(a: str | None, b: str | None) -> bool:
+    """Two spellings of one name (case and accents aside)."""
+    return a is not None and b is not None and normalize(a) == normalize(b)
+
+
+def characters_of(campaign: Campaign, player: str) -> list[Character]:
+    """The characters *player* plays, by name."""
+    played = [c for c in campaign.characters.values() if same_person(c.player_name, player)]
+    return sorted(played, key=lambda c: c.name)
+
+
+def is_present(campaign: Campaign, character: Character) -> bool:
+    """Whether *character*'s player answered the roll call; True when there was none."""
+    present = campaign.game_state.players_present
+    return not present or any(same_person(character.player_name, p) for p in present)
+
+
+def present_characters(campaign: Campaign) -> list[Character]:
+    """The characters at the table: the whole party until a roll call."""
+    return [c for c in campaign.characters.values() if is_present(campaign, c)]
+
+
+def seat(campaign: Campaign, player: str, character_ref: str | None) -> str | None:
+    """Seat *player*, with the character they play if given.
+
+    Returns a note when the character changes hands, for the model to say.
+    """
+    name = " ".join(player.split())
+    if not name:
+        raise InvalidChangeError("A player needs a name.")
+    note = None
+    if character_ref:
+        character = characters.find(campaign, character_ref)
+        previous = character.player_name
+        if previous and not same_person(previous, name):
+            note = f"{character.name} was played by {previous}, now by {name}."
+        character.player_name = name
+        character.updated_at = now()
+    state = campaign.game_state
+    if not any(same_person(p, name) for p in state.players_present):
+        state.players_present = [*state.players_present, name]
+    return note
+
+
+def leave(campaign: Campaign, player: str) -> None:
+    """Take *player* off the table; their characters stay in the party."""
+    state = campaign.game_state
+    seated = next((p for p in state.players_present if same_person(p, player)), None)
+    if seated is None:
+        at_table = ", ".join(state.players_present) or "nobody"
+        raise NotFoundError(f"{player} is not at the table. At the table: {at_table}.")
+    state.players_present = [p for p in state.players_present if p != seated]
+
+
+def clear(campaign: Campaign) -> None:
+    """Forget the last roll call: a new session starts."""
+    campaign.game_state.players_present = []

dndkit/game/sight.py

@@ -0,0 +1,142 @@
+"""Lines across the battle map: what stops an area of effect, and cover.
+
+Points are in feet, the map's top-left corner at (0, 0): square (x, y) spans
+5x to 5x+5 across and 5y to 5y+5 down. A line along a square's edge or
+through its corner passes; one crossing its inside is blocked.
+
+Cover follows the DMG (ch. 8, "Cover" on a grid): from the attacker's best
+corner, lines to the four corners of the target's square; one or two blocked
+by an obstacle give half cover, three or four three-quarters, and a target
+walled off from every corner has total cover. Creatures in the way give half
+cover at most.
+"""
+
+import math
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import battlefield, combat, grid, pathing
+from dndkit.game.grid import Square
+from dndkit.models import Campaign, Combatant, GameState
+
+Point = tuple[float, float]
+EDGE = 0.01  # how far inside a square a line must go to be blocked
+COVER = ("none", "half", "three-quarters", "total")
+COVER_BONUS = {"half": 2, "three-quarters": 5}
+_SIDES = ((-1, 0), (1, 0), (0, -1), (0, 1))  # left, right, top, bottom
+
+
+def centre(squares: Iterable[Square]) -> Point:
+    """The middle of the squares, in feet."""
+    held = list(squares)
+    xs = [x for x, _ in held]
+    ys = [y for _, y in held]
+    return ((min(xs) + max(xs) + 1) * grid.FEET / 2, (min(ys) + max(ys) + 1) * grid.FEET / 2)
+
+
+def corners(square: Square) -> list[Point]:
+    """A square's four corners, in feet."""
+    x, y = square[0] * grid.FEET, square[1] * grid.FEET
+    return [(x, y), (x + grid.FEET, y), (x, y + grid.FEET), (x + grid.FEET, y + grid.FEET)]
+
+
+def crosses(
+    a: Point, b: Point, square: Square, solid: set[Square] | frozenset[Square] = frozenset()
+) -> bool:
+    """Whether the segment a-b goes through the inside of *square* (Liang-Barsky).
+
+    A side shared with another *solid* square is no edge: a line running along
+    the seam between two wall squares is inside the wall.
+    """
+    x, y = square
+    inset = [EDGE if (x + dx, y + dy) not in solid else -EDGE for dx, dy in _SIDES]
+    x0, x1 = x * grid.FEET + inset[0], (x + 1) * grid.FEET - inset[1]
+    y0, y1 = y * grid.FEET + inset[2], (y + 1) * grid.FEET - inset[3]
+    dx, dy = b[0] - a[0], b[1] - a[1]
+    start, end = 0.0, 1.0
+    for p, q in ((-dx, a[0] - x0), (dx, x1 - a[0]), (-dy, a[1] - y0), (dy, y1 - a[1])):
+        if p == 0:
+            if q < 0:
+                return False
+            continue
+        t = q / p
+        if p < 0:
+            start = max(start, t)
+        else:
+            end = min(end, t)
+        if start > end:
+            return False
+    return True
+
+
+def blocked(a: Point, b: Point, obstacles: set[Square]) -> bool:
+    """Whether any of *obstacles* stands across the segment a-b."""
+    left, right = sorted((a[0], b[0]))
+    top, bottom = sorted((a[1], b[1]))
+    columns = range(math.floor(left / grid.FEET) - 1, math.floor(right / grid.FEET) + 2)
+    rows = range(math.floor(top / grid.FEET) - 1, math.floor(bottom / grid.FEET) + 2)
+    return any(
+        (x, y) in obstacles and crosses(a, b, (x, y), obstacles) for x in columns for y in rows
+    )
+
+
+def cover(state: GameState, attacker: Combatant, target: Combatant) -> str:
+    """The cover *target* has against *attacker*: none, half, three-quarters or total."""
+    walls = battlefield.wall_squares(battlefield.require(state))
+    mine = battlefield.footprint_of(state, attacker) or []
+    theirs = battlefield.footprint_of(state, target) or []
+    bodies = {
+        s
+        for other, held in battlefield.others(state, attacker)
+        if other is not target
+        for s in held
+    }
+    best = len(COVER) - 1
+    for corner in {point for square in mine for point in corners(square)}:
+        for square in theirs:
+            lines = [(corner, end) for end in corners(square)]
+            by_walls = sum(blocked(a, b, walls) for a, b in lines)
+            by_bodies = any(blocked(a, b, bodies) for a, b in lines)
+            if by_walls == 4:
+                level = 3
+            elif by_walls >= 3:
+                level = 2
+            else:
+                level = 1 if by_walls or by_bodies else 0
+            best = min(best, level)
+    return COVER[best]
+
+
+@dataclass(frozen=True)
+class Sightline:
+    """What bears on an attack from one combatant at another."""
+
+    attacker: Combatant
+    target: Combatant
+    feet: int
+    cover: str
+    in_reach: bool
+    pressed_by: list[str]  # foes adjacent to the attacker: its ranged attacks have disadvantage
+
+
+def look(campaign: Campaign, attacker_name: str, target_name: str) -> Sightline:
+    """Distance, cover and what else bears on *attacker_name* attacking *target_name*."""
+    state = campaign.game_state
+    attacker = combat.find(state, attacker_name)
+    target = combat.find(state, target_name)
+    mine = battlefield.footprint_of(state, attacker)
+    theirs = battlefield.footprint_of(state, target)
+    if mine is None or theirs is None:
+        raise InvalidChangeError("Both must be on the map: place_tokens first.")
+    feet = grid.feet_between(mine, theirs)
+    pressed = [
+        other.name
+        for other, held in battlefield.others(state, attacker)
+        if battlefield.is_party(other) != battlefield.is_party(attacker)
+        and grid.feet_between(mine, held) <= grid.FEET
+        and pathing.can_react(campaign, other)
+    ]
+    return Sightline(
+        attacker, target, feet, cover(state, attacker, target), feet <= attacker.reach, pressed
+    )

dndkit/game/spellbook.py

@@ -0,0 +1,97 @@
+"""Spell slots and the spells a character knows."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from dndkit.errors import InvalidChangeError, NotFoundError
+from dndkit.game import characters, registry
+from dndkit.models import Campaign, Character, Spell, now
+
+
+def set_spell_slots(campaign: Campaign, ref: str, level: int, max_slots: int) -> Character:
+    """Set how many slots of *level* a character has; 0 removes the level."""
+    character = characters.find(campaign, ref)
+    if max_slots == 0:
+        character.spell_slots.pop(level, None)
+        character.spell_slots_used.pop(level, None)
+    else:
+        character.spell_slots[level] = max_slots
+        used = character.spell_slots_used.get(level, 0)
+        character.spell_slots_used[level] = min(used, max_slots)
+    character.updated_at = now()
+    return character
+
+
+def use_spell_slot(campaign: Campaign, ref: str, level: int) -> tuple[Character, int]:
+    """Spend one slot of *level*; returns the character and the slots left."""
+    character = characters.find(campaign, ref)
+    maximum = character.spell_slots.get(level, 0)
+    if maximum == 0:
+        raise InvalidChangeError(
+            f"{character.name} has no level {level} spell slots. "
+            f"Slots: {describe_slots(character)}."
+        )
+    used = character.spell_slots_used.get(level, 0)
+    if used >= maximum:
+        raise InvalidChangeError(
+            f"{character.name} has no level {level} slot left ({used}/{maximum} used)."
+        )
+    character.spell_slots_used[level] = used + 1
+    character.updated_at = now()
+    return character, maximum - used - 1
+
+
+def describe_slots(character: Character) -> str:
+    """Slots left per level, e.g. "level 1: 2/4, level 2: 1/2"."""
+    if not character.spell_slots:
+        return "none"
+    return ", ".join(
+        f"level {level}: {maximum - character.spell_slots_used.get(level, 0)}/{maximum}"
+        for level, maximum in sorted(character.spell_slots.items())
+    )
+
+
+def set_known_spell(
+    campaign: Campaign, ref: str, spell_name: str, changes: Mapping[str, Any]
+) -> tuple[Character, Spell, bool]:
+    """Add a spell to a character's list, or change one already there.
+
+    Returns the character, the spell and whether it is new. A new spell needs
+    its level (0 for a cantrip).
+    """
+    character = characters.find(campaign, ref)
+    spell = _known(character, spell_name)
+    if spell is None:
+        if changes.get("level") is None:
+            raise InvalidChangeError(
+                f"{character.name} doesn't know '{spell_name}' yet: give its level "
+                "(0 for a cantrip) to add it."
+            )
+        spell = Spell(name=spell_name.strip(), **changes)
+        character.spells_known = [*character.spells_known, spell]
+        created = True
+    else:
+        updated = registry.revised(spell, changes)
+        character.spells_known = [updated if s is spell else s for s in character.spells_known]
+        spell, created = updated, False
+    character.updated_at = now()
+    return character, spell, created
+
+
+def forget_spell(campaign: Campaign, ref: str, spell_name: str) -> tuple[Character, Spell]:
+    """Remove a spell from a character's list."""
+    character = characters.find(campaign, ref)
+    spell = _known(character, spell_name)
+    if spell is None:
+        raise NotFoundError(
+            f"{character.name} doesn't know '{spell_name}'. "
+            f"Known spells: {registry.known_names(character.spells_known)}."
+        )
+    character.spells_known = [s for s in character.spells_known if s is not spell]
+    character.updated_at = now()
+    return character, spell
+
+
+def _known(character: Character, name: str) -> Spell | None:
+    wanted = registry.normalize(name)
+    return next((s for s in character.spells_known if registry.normalize(s.name) == wanted), None)