dndkit 0.4.0__py3-none-any.whl

dndkit/game/tables.py

@@ -0,0 +1,216 @@
+"""D&D 5e (2014) reference tables: numbers only, read by ``rules``."""
+
+# Monster XP by challenge rating (DMG ch. 9 / basic rules).
+XP_BY_CHALLENGE: dict[str, int] = {
+    "0": 10, "1/8": 25, "1/4": 50, "1/2": 100, "1": 200, "2": 450, "3": 700,
+    "4": 1100, "5": 1800, "6": 2300, "7": 2900, "8": 3900, "9": 5000, "10": 5900,
+    "11": 7200, "12": 8400, "13": 10000, "14": 11500, "15": 13000, "16": 15000,
+    "17": 18000, "18": 20000, "19": 22000, "20": 25000, "21": 33000, "22": 41000,
+    "23": 50000, "24": 62000, "25": 75000, "26": 90000, "27": 105000,
+    "28": 120000, "29": 135000, "30": 155000,
+}  # fmt: skip
+
+# XP thresholds per character level: easy, medium, hard, deadly (DMG ch. 3).
+DIFFICULTY_THRESHOLDS: dict[int, tuple[int, int, int, int]] = {
+    1: (25, 50, 75, 100), 2: (50, 100, 150, 200), 3: (75, 150, 225, 400),
+    4: (125, 250, 375, 500), 5: (250, 500, 750, 1100), 6: (300, 600, 900, 1400),
+    7: (350, 750, 1100, 1700), 8: (450, 900, 1400, 2100), 9: (550, 1100, 1600, 2400),
+    10: (600, 1200, 1900, 2800), 11: (800, 1600, 2400, 3600),
+    12: (1000, 2000, 3000, 4500), 13: (1100, 2200, 3400, 5100),
+    14: (1250, 2500, 3800, 5700), 15: (1400, 2800, 4300, 6400),
+    16: (1600, 3200, 4800, 7200), 17: (2000, 3900, 5900, 8800),
+    18: (2100, 4200, 6300, 9500), 19: (2400, 4900, 7300, 10900),
+    20: (2800, 5700, 8500, 12700),
+}  # fmt: skip
+
+# Encounter multipliers, from one monster up (DMG ch. 3); a small party uses the
+# next step up, a large party the next step down.
+ENCOUNTER_MULTIPLIERS = (0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0)
+
+# XP needed to reach each level (PHB ch. 1).
+XP_FOR_LEVEL: dict[int, int] = {
+    1: 0, 2: 300, 3: 900, 4: 2700, 5: 6500, 6: 14000, 7: 23000, 8: 34000,
+    9: 48000, 10: 64000, 11: 85000, 12: 100000, 13: 120000, 14: 140000,
+    15: 165000, 16: 195000, 17: 225000, 18: 265000, 19: 305000, 20: 355000,
+}  # fmt: skip
+
+# Spell slots per slot level for a full caster of each level (PHB ch. 3).
+FULL_CASTER_SLOTS: dict[int, tuple[int, ...]] = {
+    1: (2,), 2: (3,), 3: (4, 2), 4: (4, 3), 5: (4, 3, 2), 6: (4, 3, 3),
+    7: (4, 3, 3, 1), 8: (4, 3, 3, 2), 9: (4, 3, 3, 3, 1), 10: (4, 3, 3, 3, 2),
+    11: (4, 3, 3, 3, 2, 1), 12: (4, 3, 3, 3, 2, 1), 13: (4, 3, 3, 3, 2, 1, 1),
+    14: (4, 3, 3, 3, 2, 1, 1), 15: (4, 3, 3, 3, 2, 1, 1, 1),
+    16: (4, 3, 3, 3, 2, 1, 1, 1), 17: (4, 3, 3, 3, 2, 1, 1, 1, 1),
+    18: (4, 3, 3, 3, 3, 1, 1, 1, 1), 19: (4, 3, 3, 3, 3, 2, 1, 1, 1),
+    20: (4, 3, 3, 3, 3, 2, 2, 1, 1),
+}  # fmt: skip
+
+# Warlock pact magic per level: (number of slots, slot level).
+PACT_SLOTS: dict[int, tuple[int, int]] = {
+    1: (1, 1), 2: (2, 1), 3: (2, 2), 4: (2, 2), 5: (2, 3), 6: (2, 3), 7: (2, 4),
+    8: (2, 4), 9: (2, 5), 10: (2, 5), 11: (3, 5), 12: (3, 5), 13: (3, 5),
+    14: (3, 5), 15: (3, 5), 16: (3, 5), 17: (4, 5), 18: (4, 5), 19: (4, 5),
+    20: (4, 5),
+}  # fmt: skip
+
+# Class -> (hit die, spellcasting progression).
+CLASSES: dict[str, tuple[int, str]] = {
+    "artificer": (8, "half_up"),
+    "barbarian": (12, "none"),
+    "bard": (8, "full"),
+    "cleric": (8, "full"),
+    "druid": (8, "full"),
+    "fighter": (10, "none"),
+    "monk": (8, "none"),
+    "paladin": (10, "half"),
+    "ranger": (10, "half"),
+    "rogue": (8, "none"),
+    "sorcerer": (6, "full"),
+    "warlock": (8, "pact"),
+    "wizard": (6, "full"),
+}
+
+# Class names as players say them, French included, in both genders (and both
+# translations of warlock).
+CLASS_ALIASES: dict[str, str] = {
+    "artificier": "artificer",
+    "artificiere": "artificer",
+    "barbare": "barbarian",
+    "barde": "bard",
+    "clerc": "cleric",
+    "pretre": "cleric",
+    "pretresse": "cleric",
+    "druide": "druid",
+    "druidesse": "druid",
+    "guerrier": "fighter",
+    "guerriere": "fighter",
+    "moine": "monk",
+    "moniale": "monk",
+    "paladine": "paladin",
+    "rodeur": "ranger",
+    "rodeuse": "ranger",
+    "roublard": "rogue",
+    "roublarde": "rogue",
+    "voleur": "rogue",
+    "voleuse": "rogue",
+    "ensorceleur": "sorcerer",
+    "ensorceleuse": "sorcerer",
+    "occultiste": "warlock",
+    "sorcier": "warlock",
+    "sorciere": "warlock",
+    "magicien": "wizard",
+    "magicienne": "wizard",
+    "mage": "wizard",
+}
+
+# Walking speed 25 feet (PHB races); every other race walks 30.
+SLOW_RACES = frozenset({"dwarf", "nain", "naine", "halfling", "halfelin", "halfeline", "gnome"})
+
+# DMG ch. 9, "Monster Statistics by Challenge Rating": armor class, hit points
+# (low, high), attack bonus, damage per round (low, high), save DC.
+MONSTER_STATS: dict[str, tuple[int, tuple[int, int], int, tuple[int, int], int]] = {
+    "0": (13, (1, 6), 3, (0, 1), 13),
+    "1/8": (13, (7, 35), 3, (2, 3), 13),
+    "1/4": (13, (36, 49), 3, (4, 5), 13),
+    "1/2": (13, (50, 70), 3, (6, 8), 13),
+    "1": (13, (71, 85), 3, (9, 14), 13),
+    "2": (13, (86, 100), 3, (15, 20), 13),
+    "3": (13, (101, 115), 4, (21, 26), 13),
+    "4": (14, (116, 130), 5, (27, 32), 14),
+    "5": (15, (131, 145), 6, (33, 38), 15),
+    "6": (15, (146, 160), 6, (39, 44), 15),
+    "7": (15, (161, 175), 6, (45, 50), 15),
+    "8": (16, (176, 190), 7, (51, 56), 16),
+    "9": (16, (191, 205), 7, (57, 62), 16),
+    "10": (17, (206, 220), 7, (63, 68), 16),
+    "11": (17, (221, 235), 8, (69, 74), 17),
+    "12": (17, (236, 250), 8, (75, 80), 17),
+    "13": (18, (251, 265), 8, (81, 86), 18),
+    "14": (18, (266, 280), 8, (87, 92), 18),
+    "15": (18, (281, 295), 8, (93, 98), 18),
+    "16": (18, (296, 310), 9, (99, 104), 18),
+    "17": (19, (311, 325), 10, (105, 110), 19),
+    "18": (19, (326, 340), 10, (111, 116), 19),
+    "19": (19, (341, 355), 10, (117, 122), 19),
+    "20": (19, (356, 400), 10, (123, 140), 19),
+    "21": (19, (401, 445), 11, (141, 158), 20),
+    "22": (19, (446, 490), 11, (159, 176), 20),
+    "23": (19, (491, 535), 11, (177, 194), 20),
+    "24": (19, (536, 580), 12, (195, 212), 21),
+    "25": (19, (581, 625), 12, (213, 230), 21),
+    "26": (19, (626, 670), 12, (231, 248), 21),
+    "27": (19, (671, 715), 13, (249, 266), 22),
+    "28": (19, (716, 760), 13, (267, 284), 22),
+    "29": (19, (761, 805), 13, (285, 302), 22),
+    "30": (19, (806, 850), 14, (303, 320), 23),
+}
+
+# The ability each class casts its spells with (PHB ch. 3).
+CASTING_ABILITY: dict[str, str] = {
+    "artificer": "intelligence",
+    "bard": "charisma",
+    "cleric": "wisdom",
+    "druid": "wisdom",
+    "paladin": "charisma",
+    "ranger": "wisdom",
+    "sorcerer": "charisma",
+    "warlock": "charisma",
+    "wizard": "intelligence",
+}
+
+
+# PHB ch. 7: each skill and its ability.
+SKILLS: dict[str, str] = {
+    "Acrobatics": "dexterity",
+    "Animal Handling": "wisdom",
+    "Arcana": "intelligence",
+    "Athletics": "strength",
+    "Deception": "charisma",
+    "History": "intelligence",
+    "Insight": "wisdom",
+    "Intimidation": "charisma",
+    "Investigation": "intelligence",
+    "Medicine": "wisdom",
+    "Nature": "intelligence",
+    "Perception": "wisdom",
+    "Performance": "charisma",
+    "Persuasion": "charisma",
+    "Religion": "intelligence",
+    "Sleight of Hand": "dexterity",
+    "Stealth": "dexterity",
+    "Survival": "wisdom",
+}
+
+# The French names (official translation) of the skills that change.
+SKILL_ALIASES: dict[str, str] = {
+    "acrobaties": "Acrobatics",
+    "dressage": "Animal Handling",
+    "arcanes": "Arcana",
+    "athletisme": "Athletics",
+    "tromperie": "Deception",
+    "histoire": "History",
+    "perspicacite": "Insight",
+    "intuition": "Insight",
+    "medecine": "Medicine",
+    "representation": "Performance",
+    "escamotage": "Sleight of Hand",
+    "discretion": "Stealth",
+    "survie": "Survival",
+}
+
+# PHB ch. 3: the two saving throws each class is proficient in.
+CLASS_SAVES: dict[str, tuple[str, str]] = {
+    "artificer": ("constitution", "intelligence"),
+    "barbarian": ("strength", "constitution"),
+    "bard": ("dexterity", "charisma"),
+    "cleric": ("wisdom", "charisma"),
+    "druid": ("intelligence", "wisdom"),
+    "fighter": ("strength", "constitution"),
+    "monk": ("strength", "dexterity"),
+    "paladin": ("wisdom", "charisma"),
+    "ranger": ("strength", "dexterity"),
+    "rogue": ("dexterity", "intelligence"),
+    "sorcerer": ("constitution", "charisma"),
+    "warlock": ("wisdom", "charisma"),
+    "wizard": ("intelligence", "wisdom"),
+}

dndkit/game/world.py

@@ -0,0 +1,125 @@
+"""NPCs, locations and quests, and removing any campaign entity."""
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+from dndkit.errors import NotFoundError
+from dndkit.game import combat, registry
+from dndkit.models import NPC, Campaign, Location, Quest, QuestStatus
+
+EntityKind = Literal["character", "npc", "location", "quest"]
+NPC_KIND = "NPC"
+LOCATION_KIND = "location"
+QUEST_KIND = "quest"
+
+# kind -> (Campaign attribute, label used in messages)
+_COLLECTIONS: dict[str, tuple[str, str]] = {
+    "character": ("characters", "character"),
+    "npc": ("npcs", NPC_KIND),
+    "location": ("locations", LOCATION_KIND),
+    "quest": ("quests", QUEST_KIND),
+}
+
+
+def find_entity(campaign: Campaign, kind: EntityKind, ref: str) -> registry.Named:
+    """The character, NPC, location or quest *ref* names."""
+    attribute, label = _COLLECTIONS[kind]
+    found: registry.Named = registry.find(getattr(campaign, attribute), ref, label)
+    return found
+
+
+def remove_entity(campaign: Campaign, kind: EntityKind, ref: str) -> str:
+    """Remove a character, NPC, location or quest; returns its name. A character
+    leaves the running fight too."""
+    attribute, label = _COLLECTIONS[kind]
+    removed: registry.Named = registry.remove(getattr(campaign, attribute), ref, label)
+    state = campaign.game_state
+    for fighter in [c for c in state.initiative_order if c.character_id == removed.id]:
+        combat.remove(state, fighter.name, overcome=False)
+    return removed.name
+
+
+def find_npc(campaign: Campaign, ref: str) -> NPC:
+    """The NPC *ref* names."""
+    return registry.find(campaign.npcs, ref, NPC_KIND)
+
+
+def create_npc(campaign: Campaign, npc: NPC) -> NPC:
+    """Add an NPC; the name must be free."""
+    return registry.add(campaign.npcs, npc, NPC_KIND)
+
+
+def update_npc(campaign: Campaign, ref: str, changes: Mapping[str, Any]) -> NPC:
+    """Change an NPC's fields."""
+    return registry.update(campaign.npcs, ref, NPC_KIND, changes)
+
+
+def find_location(campaign: Campaign, ref: str) -> Location:
+    """The location *ref* names."""
+    return registry.find(campaign.locations, ref, LOCATION_KIND)
+
+
+def create_location(campaign: Campaign, location: Location) -> Location:
+    """Add a location; the name must be free."""
+    return registry.add(campaign.locations, location, LOCATION_KIND)
+
+
+def update_location(campaign: Campaign, ref: str, changes: Mapping[str, Any]) -> Location:
+    """Change a location's fields."""
+    return registry.update(campaign.locations, ref, LOCATION_KIND, changes)
+
+
+def find_quest(campaign: Campaign, ref: str) -> Quest:
+    """The quest *ref* names (title or ID)."""
+    return registry.find(campaign.quests, ref, QUEST_KIND)
+
+
+def create_quest(campaign: Campaign, quest: Quest) -> Quest:
+    """Add a quest; the title must be free."""
+    return registry.add(campaign.quests, quest, QUEST_KIND)
+
+
+def update_quest(
+    campaign: Campaign,
+    ref: str,
+    *,
+    status: QuestStatus | None = None,
+    complete_objective: str | None = None,
+    add_objective: str | None = None,
+    notes: str | None = None,
+) -> tuple[Quest, list[str]]:
+    """Change a quest; returns it with a line per change made."""
+    quest = find_quest(campaign, ref)
+    changes: list[str] = []
+    if add_objective and add_objective not in quest.objectives:
+        quest.objectives = [*quest.objectives, add_objective]
+        changes.append(f"new objective '{add_objective}'")
+    if complete_objective:
+        objective = _match_objective(quest, complete_objective)
+        if objective not in quest.completed_objectives:
+            quest.completed_objectives = [*quest.completed_objectives, objective]
+        changes.append(f"objective done: '{objective}'")
+    if status:
+        quest.status = status
+        changes.append(f"status {status}")
+    if notes is not None:
+        quest.notes = notes
+        changes.append("notes updated")
+    return quest, changes
+
+
+def _match_objective(quest: Quest, ref: str) -> str:
+    """An objective by number ("2"), exact text, or a fragment only it contains."""
+    text = ref.strip()
+    if text.isdigit() and 1 <= int(text) <= len(quest.objectives):
+        return quest.objectives[int(text) - 1]
+    wanted = registry.normalize(text)
+    exact = [o for o in quest.objectives if registry.normalize(o) == wanted]
+    partial = [o for o in quest.objectives if wanted and wanted in registry.normalize(o)]
+    matches = exact or partial
+    if len(matches) == 1:
+        return matches[0]
+    listed = "; ".join(f"{i}. {o}" for i, o in enumerate(quest.objectives, 1)) or "none"
+    raise NotFoundError(
+        f"Quest '{quest.title}' has no single objective matching '{ref}'. Objectives: {listed}."
+    )

dndkit/models/__init__.py

@@ -0,0 +1,69 @@
+"""Pydantic models for campaigns, characters and the world."""
+
+from dndkit.models.base import GameModel, new_id, now
+from dndkit.models.battle import Battlefield, Layout, Placement
+from dndkit.models.bestiary import (
+    Encounter,
+    EncounterGroup,
+    EncounterStatus,
+    Monster,
+    Size,
+)
+from dndkit.models.campaign import (
+    AdventureEvent,
+    Campaign,
+    Combatant,
+    CombatRecord,
+    EventType,
+    GameState,
+    Participant,
+    Seat,
+    SessionNote,
+)
+from dndkit.models.character import (
+    ABILITIES,
+    CONDITIONS,
+    AbilityScore,
+    Character,
+    CharacterClass,
+    Item,
+    Race,
+    Spell,
+)
+from dndkit.models.world import NPC, Attitude, Location, Quest, QuestStatus
+
+__all__ = [
+    "ABILITIES",
+    "CONDITIONS",
+    "NPC",
+    "AbilityScore",
+    "AdventureEvent",
+    "Attitude",
+    "Battlefield",
+    "Campaign",
+    "Character",
+    "CharacterClass",
+    "Combatant",
+    "CombatRecord",
+    "Encounter",
+    "EncounterGroup",
+    "EncounterStatus",
+    "EventType",
+    "GameModel",
+    "GameState",
+    "Item",
+    "Layout",
+    "Location",
+    "Monster",
+    "Participant",
+    "Placement",
+    "Quest",
+    "QuestStatus",
+    "Race",
+    "Seat",
+    "SessionNote",
+    "Size",
+    "Spell",
+    "new_id",
+    "now",
+]

dndkit/models/base.py

@@ -0,0 +1,26 @@
+"""Shared base for the game's data models."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+from shortuuid import random as short_random
+
+
+def new_id() -> str:
+    """A random 8-character ID."""
+    return short_random(length=8)
+
+
+def now() -> datetime:
+    """The current local time, for created/updated stamps."""
+    return datetime.now()
+
+
+class GameModel(BaseModel):
+    """Assignments are validated; keys left by older versions are ignored on load.
+
+    No validator may assign to ``self``: with ``validate_assignment`` that
+    assignment would validate again and recurse.
+    """
+
+    model_config = ConfigDict(validate_assignment=True, extra="ignore")

dndkit/models/battle.py

@@ -0,0 +1,40 @@
+"""The battle map a fight is played on."""
+
+from pydantic import Field
+
+from dndkit.models.base import GameModel
+
+MAX_SQUARES = 26  # columns are single letters, A to Z
+
+
+class Battlefield(GameModel):
+    """A grid of 5-foot squares named like "D7": column letter, row number, A1 top left.
+
+    Terrain lists squares by name; who stands where lives on each combatant.
+    ``area`` is the last area of effect, drawn until the next turn.
+    """
+
+    width: int = Field(ge=1, le=MAX_SQUARES)
+    height: int = Field(ge=1, le=MAX_SQUARES)
+    walls: list[str] = Field(default_factory=list)  # blocked squares
+    difficult: list[str] = Field(default_factory=list)  # each costs 10 feet to enter
+    area: list[str] = Field(default_factory=list)
+    area_label: str | None = None
+
+
+class Layout(GameModel):
+    """A battle map as a tool call describes it."""
+
+    width: int = Field(ge=1, le=MAX_SQUARES, description="Squares across")
+    height: int = Field(ge=1, le=MAX_SQUARES, description="Squares down")
+    walls: list[str] = Field(default_factory=list, description='e.g. "C3" or "C1:C6"')
+    difficult: list[str] = Field(default_factory=list, description="Difficult terrain")
+
+
+class Placement(GameModel):
+    """A combatant put on a square, or hidden or revealed, as a tool call describes it."""
+
+    who: str = Field(min_length=1, description="Combatant name")
+    at: str | None = Field(default=None, description="Square, e.g. D7")
+    ally: bool | None = Field(default=None, description="Fights with the party")
+    hidden: bool | None = Field(default=None, description="Unseen by the players")

dndkit/models/bestiary.py

@@ -0,0 +1,56 @@
+"""The campaign's bestiary and its planned encounters."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from dndkit.models.base import GameModel, new_id
+from dndkit.models.battle import Battlefield
+
+EncounterStatus = Literal["planned", "running", "done"]
+Size = Literal["tiny", "small", "medium", "large", "huge", "gargantuan"]
+
+
+class Monster(GameModel):
+    """A stat block the game master saved, used to fill combatants in."""
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    armor_class: int = Field(ge=0)
+    hit_points: int = Field(ge=1)
+    challenge_rating: str | None = None  # "1/4", "2", ...
+    xp: int = Field(default=0, ge=0)
+    initiative_bonus: int = 0
+    speed: str | None = None  # "30 ft., fly 60 ft."
+    size: Size = "medium"
+    actions: str = ""  # free text: attacks, damage, special abilities
+    notes: str = ""
+    boss: bool = False
+    legendary_actions: int = Field(default=0, ge=0, le=5)  # a round's worth
+    legendary_resistances: int = Field(default=0, ge=0, le=5)  # a day's worth
+
+
+class EncounterGroup(GameModel):
+    """How many of one bestiary monster an encounter holds."""
+
+    monster: str = Field(min_length=1, description="Bestiary monster name")
+    count: int = Field(default=1, ge=1, le=50, description="How many")
+    at: list[str] = Field(default_factory=list, description="Their squares, if a map")
+    hidden: bool = Field(default=False, description="Unseen at first (ambush)")
+
+
+class Encounter(GameModel):
+    """A fight prepared in advance, started with start_combat(encounter=...).
+
+    Older saves stored an unused ``CombatEncounter`` under the same key; its
+    extra fields are ignored and its ``description`` still fits.
+    """
+
+    id: str = Field(default_factory=new_id)
+    name: str = Field(min_length=1)
+    description: str = ""
+    monsters: list[EncounterGroup] = Field(default_factory=list)
+    location: str | None = None
+    status: EncounterStatus = "planned"
+    notes: str = ""
+    battlefield: Battlefield | None = None  # laid out when the fight starts