dndkit 0.4.0__py3-none-any.whl

dndkit/views/battle.py

@@ -0,0 +1,92 @@
+"""The battle map as the screens draw it: terrain, tokens, where the actor can go.
+
+The game master's screens get exact hit points; the players' get how hurt a
+foe looks, and see where a creature can move only on their own side's turns.
+"""
+
+from dndkit.game import battlefield, grid, movement, pathing
+from dndkit.models import Campaign, Combatant
+
+Json = dict[str, object]
+
+
+def health(hit_points: int | None, maximum: int | None) -> str | None:
+    """How hurt a creature looks: unhurt, hurt, bloodied (half or less) or down."""
+    if hit_points is None or not maximum:
+        return None
+    if hit_points <= 0:
+        return "down"
+    if hit_points >= maximum:
+        return "unhurt"
+    return "bloodied" if hit_points * 2 <= maximum else "hurt"
+
+
+def battle_map(campaign: Campaign, public: bool) -> Json | None:
+    """The map for drawing, or None when the fight has none."""
+    state = campaign.game_state
+    field = state.battlefield
+    if field is None:
+        return None
+    current = state.current_combatant
+    tokens = [
+        _token(campaign, c, c is current, public)
+        for c in state.initiative_order
+        if c.position is not None and not (public and unseen(c))
+    ]
+    shows_moves = current is not None and (not public or battlefield.is_party(current))
+    return {
+        "width": field.width,
+        "height": field.height,
+        "walls": [list(s) for s in sorted(battlefield.wall_squares(field))],
+        "difficult": [list(s) for s in sorted(battlefield.difficult_squares(field))],
+        "area": [list(grid.parse(s, field)) for s in field.area],
+        "area_label": field.area_label,
+        "tokens": tokens,
+        "moves": _moves(campaign, current, public) if shows_moves and current else [],
+    }
+
+
+def unseen(combatant: Combatant) -> bool:
+    """A foe hidden from the players: kept off their screens altogether."""
+    return combatant.hidden and not battlefield.is_party(combatant)
+
+
+def _token(campaign: Campaign, combatant: Combatant, current: bool, public: bool) -> Json:
+    x, y = battlefield.square_of(campaign.game_state, combatant) or (0, 0)
+    character = campaign.characters.get(combatant.character_id or "")
+    hp: int | None
+    hp_max: int | None
+    if character is not None:
+        hp, hp_max = character.hit_points_current, character.hp_maximum
+    else:
+        hp, hp_max = combatant.hit_points, combatant.hit_points_max
+    token: Json = {
+        "name": combatant.name,
+        "x": x,
+        "y": y,
+        "size": grid.SIZE_SQUARES[combatant.size],
+        "party": battlefield.is_party(combatant),
+        "current": current,
+        "down": hp == 0,
+        "hidden": combatant.hidden,
+        "boss": combatant.boss,
+    }
+    if public and character is None:
+        token["health"] = health(hp, hp_max)
+    else:
+        token.update(hp=hp, hp_max=hp_max)
+    return token
+
+
+def _moves(campaign: Campaign, mover: Combatant, public: bool) -> list[list[int]]:
+    """The squares *mover* can still reach this turn."""
+    start = battlefield.square_of(campaign.game_state, mover)
+    left = movement.movement_left(campaign, mover)
+    if start is None or left == 0:
+        return []
+    ground = pathing.Ground(campaign, mover, provokes=False, as_players_see=public)
+    return [
+        list(square)
+        for square, route in pathing.routes(ground, start).items()
+        if 0 < route.feet <= left and ground.standable(square)
+    ]

dndkit/views/desk.py

@@ -0,0 +1,76 @@
+"""The game master's desk, to follow and debug the model: what it called,
+the campaign's notebook, the full sheets, and the server's own facts."""
+
+import time
+from pathlib import Path
+
+from dndkit import __version__
+from dndkit.activity import ActivityLog
+from dndkit.models import Campaign
+from dndkit.skills import load_catalog
+from dndkit.views import everyone
+from dndkit.views.everyone import Json
+
+SHOWN_CALLS = 60
+SHOWN_SESSIONS = 6
+
+
+def activity(log: ActivityLog) -> Json:
+    """The model's latest calls, newest first."""
+    calls = log.recent()[-SHOWN_CALLS:]
+    return {
+        "calls": [
+            {
+                "n": c.number,
+                "time": time.strftime("%H:%M:%S", time.localtime(c.at)),
+                "kind": c.kind,
+                "name": c.name,
+                "arguments": c.arguments,
+                "outcome": c.outcome,
+                "failed": c.failed,
+                "ms": c.milliseconds,
+            }
+            for c in reversed(calls)
+        ],
+        "failures": sum(c.failed for c in calls),
+    }
+
+
+def notebook(campaign: Campaign, saved_in: Path | None, data_dir: Path) -> Json:
+    """The campaign as the model's tools hold it, beyond the board: notes, the
+    setting, past sessions, and where it all lives."""
+    state = campaign.game_state
+    return {
+        "situation": state.notes,
+        "world_notes": campaign.world_notes,
+        "setting": campaign.setting,
+        "dm": campaign.dm_name,
+        "sessions": [
+            {
+                "number": s.session_number,
+                "title": s.title,
+                "summary": s.summary,
+                "moments": s.events,
+                "present": s.characters_present,
+                "xp": s.experience_gained,
+                "treasure": s.treasure_found,
+                "notes": s.notes,
+            }
+            for s in sorted(campaign.sessions, key=lambda s: s.session_number)[-SHOWN_SESSIONS:]
+        ],
+        "server": {
+            "version": __version__,
+            "data_dir": str(data_dir),
+            "file": saved_in.name if saved_in else None,
+            "saved": campaign.updated_at.astimezone().strftime("%Y-%m-%d %H:%M:%S"),
+            "skills": [s.name for s in load_catalog()],
+        },
+    }
+
+
+def sheets(campaign: Campaign) -> Json:
+    """Every character's full sheet, with the game master's notes on it."""
+    party = sorted(campaign.characters.values(), key=lambda c: c.name)
+    return {
+        "sheets": [{**everyone.character(campaign, c.id), "notes": c.notes} for c in party],
+    }

dndkit/views/everyone.py

@@ -0,0 +1,194 @@
+"""What everyone at the table may see: the dice, the party, the seats, a sheet.
+
+Each view lists the fields it sends. The MCP widgets, the table screen and the
+players' phones all show these; the game master's views (``widgets``, ``desk``)
+add their own on top, so nothing here may hold a secret: a foe's numbers, a
+plan, the game master's notes.
+"""
+
+from typing import Any
+
+from dndkit.game import characters, proficiencies, seating
+from dndkit.game.dice import DiceLog, LoggedRoll
+from dndkit.game.tables import XP_FOR_LEVEL
+from dndkit.models import ABILITIES, Campaign, Character, Item, Spell
+from dndkit.views.battle import unseen
+
+Json = dict[str, Any]
+
+
+def dice(log: DiceLog, limit: int = 6, secrets: bool = False) -> Json:
+    """The latest rolls, newest last; the secret ones only for the game master."""
+    shown = [roll for roll in log.recent() if secrets or not roll.secret]
+    return {"rolls": [_roll(roll) for roll in shown[-limit:]]}
+
+
+def _roll(roll: LoggedRoll) -> Json:
+    result = roll.result
+    return {
+        "n": roll.number,
+        "t": roll.at,
+        "secret": roll.secret,
+        "notation": result.notation,
+        "total": result.total,
+        "mode": result.mode,
+        "terms": [
+            {"sign": t.sign, "sides": t.sides, "faces": list(t.faces), "kept": t.kept}
+            for t in result.terms
+        ],
+    }
+
+
+def party(campaign: Campaign) -> Json:
+    """Where the party stands, every character's vitals and the quests' progress."""
+    state = campaign.game_state
+    current = state.current_combatant
+    return {
+        "campaign": campaign.name,
+        "description": campaign.description,
+        "session": state.current_session,
+        "location": state.current_location,
+        "date": state.current_date_in_game,
+        "funds": state.party_funds,
+        "in_combat": state.in_combat,
+        "round": state.combat_round,
+        # The players' pages show this too: a hidden foe's turn names no one.
+        "current": current.name if current and not unseen(current) else None,
+        "characters": [
+            {
+                "name": c.name,
+                "summary": _summary(c),
+                "player": c.player_name,
+                "present": seating.is_present(campaign, c),
+                **vitals(c),
+            }
+            for c in sorted(campaign.characters.values(), key=lambda c: c.name)
+        ],
+        "quests": [
+            {"title": q.title, "done": len(q.completed_objectives), "total": len(q.objectives)}
+            for q in campaign.quests.values()
+            if q.status == "active"
+        ],
+    }
+
+
+def seating_chart(campaign: Campaign) -> Json:
+    """Who sits at the table in seat order, with their characters, and who is missing."""
+    state = campaign.game_state
+    party = sorted(campaign.characters.values(), key=lambda c: c.name)
+    return {
+        "campaign": campaign.name,
+        "session": state.current_session,
+        "called": bool(state.players_present),
+        "seats": [
+            {
+                "player": player,
+                "characters": [
+                    {"name": c.name, "summary": _summary(c)}
+                    for c in seating.characters_of(campaign, player)
+                ],
+            }
+            for player in state.players_present
+        ],
+        # Before the roll call: the players known so far.
+        "absent": [
+            {"name": c.name, "player": c.player_name}
+            for c in party
+            if c.player_name and (not state.players_present or not seating.is_present(campaign, c))
+        ],
+        "unplayed": [c.name for c in party if not c.player_name],
+    }
+
+
+def character(campaign: Campaign, ref: str) -> Json:
+    """One character's sheet, as its player sees it (the game master's notes left out)."""
+    c = characters.find(campaign, ref)
+    level = c.character_class.level
+    casting = characters.spellcasting(c)
+    return {
+        "name": c.name,
+        "summary": _summary(c),
+        "player": c.player_name,
+        "background": c.background,
+        "alignment": c.alignment,
+        "description": c.description,
+        "bio": c.bio,
+        "abilities": [
+            {"key": key[:3], "score": c.abilities[key].score, "mod": c.abilities[key].mod}
+            for key in ABILITIES
+            if key in c.abilities
+        ],
+        "proficiency": c.proficiency_bonus,
+        "speed": c.speed,
+        "initiative": characters.initiative(c),
+        "hit_dice": c.hit_dice_remaining,
+        "casting": (
+            {"ability": casting.ability, "attack": casting.attack, "dc": casting.save_dc}
+            if casting
+            else None
+        ),
+        "xp": c.experience_points,
+        "next_level_xp": XP_FOR_LEVEL.get(level + 1),
+        "inspiration": c.inspiration,
+        "race": {"name": c.race.name, "subrace": c.race.subrace, "traits": c.race.traits},
+        "inventory": [_item(i) for i in c.inventory],
+        "equipment": [
+            {"slot": slot, **_item(item)} for slot, item in c.equipment.items() if item is not None
+        ],
+        "spells": [_spell(s) for s in sorted(c.spells_known, key=lambda s: (s.level, s.name))],
+        "features": c.features_and_traits,
+        "skills": [{"name": p.name, "bonus": p.bonus} for p in proficiencies.skill_bonuses(c)],
+        "saves": [{"name": p.name[:3], "bonus": p.bonus} for p in proficiencies.save_bonuses(c)],
+        "languages": c.languages,
+        **vitals(c),
+    }
+
+
+def _item(i: Item) -> Json:
+    details = [i.item_type if i.item_type != "misc" else "", i.value or ""]
+    if i.weight:
+        details.append(f"{i.weight:g} lb")
+    return {
+        "name": i.name,
+        "qty": i.quantity,
+        "description": i.description,
+        "details": " · ".join(d for d in details if d),
+    }
+
+
+def _spell(s: Spell) -> Json:
+    components = ", ".join(s.components)
+    if s.material_components:
+        components += f" ({s.material_components})"
+    details = [s.school, s.casting_time, str(s.range) if s.range else "", s.duration, components]
+    return {
+        "name": s.name,
+        "level": s.level,
+        "prepared": s.prepared,
+        "details": " · ".join(d for d in details if d),
+        "description": s.description,
+    }
+
+
+def _summary(c: Character) -> str:
+    return f"{c.race.name} {c.character_class.name} {c.character_class.level}"
+
+
+def vitals(c: Character) -> Json:
+    """Hit points, defenses and resources: what the whole table may see of a character."""
+    return {
+        "hp": c.hit_points_current,
+        "hp_max": c.hp_maximum,
+        "temp": c.temporary_hit_points,
+        "ac": c.armor_class,
+        "conditions": c.conditions,
+        "rounds": c.condition_rounds,
+        "concentration": c.concentration,
+        "exhaustion": c.exhaustion,
+        "death_saves": [c.death_saves_success, c.death_saves_failure],
+        "stable": c.stable,
+        "slots": [
+            [level, maximum - c.spell_slots_used.get(level, 0), maximum]
+            for level, maximum in sorted(c.spell_slots.items())
+        ],
+    }

dndkit/views/public.py

@@ -0,0 +1,89 @@
+"""What the players may see: the table screen and each player's phone.
+
+Built field by field from what is allowed, never by trimming the game
+master's views, so a field added to a model stays hidden until it is added
+here. Players see their party in full, but never an NPC's biography or notes,
+a planned encounter, a monster's statistics, or a foe hidden from them: a
+monster's hit points show as how hurt it looks.
+"""
+
+from dndkit.models import Campaign, Combatant
+from dndkit.views.battle import battle_map, health, unseen
+from dndkit.views.everyone import Json, vitals
+
+JOURNAL_EVENTS = 8
+
+
+def combat(campaign: Campaign) -> Json:
+    """The initiative order; monsters without their numbers."""
+    state = campaign.game_state
+    current = state.current_combatant
+    return {
+        "in_combat": state.in_combat,
+        "round": state.combat_round,
+        "order": [
+            _fighter(campaign, c, c is current) for c in state.initiative_order if not unseen(c)
+        ],
+        "defeated": [c.name for c in state.defeated if not unseen(c)],
+        "xp": sum(c.xp for c in state.defeated if not unseen(c)),
+        "map": battle_map(campaign, public=True),
+    }
+
+
+def _fighter(campaign: Campaign, combatant: Combatant, current: bool) -> Json:
+    seen = {
+        "name": combatant.name,
+        "initiative": combatant.initiative,
+        "current": current,
+        "position": combatant.position,
+        "boss": combatant.boss,
+    }
+    character = campaign.characters.get(combatant.character_id or "")
+    if character is not None:
+        return {**seen, "pc": True, **vitals(character)}
+    return {
+        **seen,
+        "pc": False,
+        "health": health(combatant.hit_points, combatant.hit_points_max),
+        "conditions": list(combatant.conditions),
+        "rounds": dict(combatant.condition_rounds),
+    }
+
+
+def journal(campaign: Campaign, limit: int = JOURNAL_EVENTS, full: bool = False) -> Json:
+    """Active quests with their objectives, and the latest moments of the adventure log."""
+    return {
+        "quests": [
+            {
+                "title": q.title,
+                "giver": q.giver,
+                "description": q.description,
+                "objectives": [
+                    {"text": text, "done": text in q.completed_objectives} for text in q.objectives
+                ],
+            }
+            for q in campaign.quests.values()
+            if q.status == "active"
+        ],
+        "events": [
+            {
+                "title": e.title,
+                "description": e.description,
+                "type": e.event_type.value,
+                "location": e.location,
+                # The game master's own log adds what the players do not need.
+                **(
+                    {
+                        "session": e.session_number,
+                        "importance": e.importance,
+                        "characters": e.characters_involved,
+                        "tags": e.tags,
+                    }
+                    if full
+                    else {}
+                ),
+            }
+            for e in reversed(campaign.events[-limit:])
+        ],
+        "total": len(campaign.events),
+    }

dndkit/views/widgets.py

@@ -0,0 +1,58 @@
+"""The fight as the game master sees it, in the MCP widget and the web backstage.
+
+Monsters' exact hit points, hidden foes and legendary uses show here; what
+the players may see is built separately, field by field, in ``views.public``
+and ``views.everyone``.
+"""
+
+from dndkit.models import Campaign, Combatant
+from dndkit.views.battle import battle_map
+from dndkit.views.everyone import Json, vitals
+
+
+def combat(campaign: Campaign) -> Json:
+    """The initiative order with live hit points, and who has fallen."""
+    state = campaign.game_state
+    current = state.current_combatant
+    return {
+        "in_combat": state.in_combat,
+        "round": state.combat_round,
+        "order": [_combatant(campaign, c, c is current) for c in state.initiative_order],
+        "defeated": [c.name for c in state.defeated],
+        "xp": sum(c.xp for c in state.defeated),
+        "map": battle_map(campaign, public=False),
+        "last": (
+            state.last_combat.model_dump(mode="json")
+            if state.last_combat and not state.in_combat
+            else None
+        ),
+    }
+
+
+def _combatant(campaign: Campaign, combatant: Combatant, current: bool) -> Json:
+    character = campaign.characters.get(combatant.character_id or "")
+    if character is not None:
+        stats = vitals(character)
+    else:
+        stats = {
+            "hp": combatant.hit_points,
+            "hp_max": combatant.hit_points_max,
+            "temp": 0,
+            "ac": combatant.armor_class,
+            "conditions": combatant.conditions,
+            "rounds": combatant.condition_rounds,
+            "concentration": combatant.concentration,
+        }
+    return {
+        "name": combatant.name,
+        "initiative": combatant.initiative,
+        "pc": character is not None,
+        "current": current,
+        "position": combatant.position,
+        "hidden": combatant.hidden,
+        "reaction_used": combatant.reaction_used,
+        "boss": combatant.boss,
+        "legendary": [combatant.legendary_actions_left, combatant.legendary_actions],
+        "resistances": combatant.legendary_resistances_left,
+        **stats,
+    }

dndkit/views/world.py

@@ -0,0 +1,70 @@
+"""The world as the game master knows it: NPCs, places and the bestiary, secrets included."""
+
+from dndkit.models import NPC, Campaign, Location, Monster
+from dndkit.text import normalize
+from dndkit.views.everyone import Json
+
+
+def world(campaign: Campaign) -> Json:
+    """Every NPC, location and stat block, by name."""
+    here = normalize(campaign.game_state.current_location or "")
+    fighting = [c.monster for c in campaign.game_state.initiative_order if c.monster]
+    return {
+        "npcs": [_npc(n) for n in sorted(campaign.npcs.values(), key=lambda n: n.name)],
+        "locations": [
+            _location(place, normalize(place.name) == here)
+            for place in sorted(campaign.locations.values(), key=lambda p: p.name)
+        ],
+        "monsters": [
+            _monster(m, fighting.count(m.name))
+            for m in sorted(campaign.monsters.values(), key=lambda m: m.name)
+        ],
+    }
+
+
+def _npc(npc: NPC) -> Json:
+    return {
+        "name": npc.name,
+        "race": npc.race,
+        "occupation": npc.occupation,
+        "location": npc.location,
+        "attitude": npc.attitude,
+        "description": npc.description,
+        "bio": npc.bio,
+        "notes": npc.notes,
+        "ties": [f"{who}: {what}" for who, what in npc.relationships.items()],
+        "stats": [f"{key}: {value}" for key, value in (npc.stats or {}).items()],
+    }
+
+
+def _location(place: Location, current: bool) -> Json:
+    return {
+        "name": place.name,
+        "type": place.location_type,
+        "current": current,
+        "description": place.description,
+        "population": place.population,
+        "government": place.government,
+        "features": place.notable_features,
+        "npcs": place.npcs,
+        "connections": place.connections,
+        "notes": place.notes,
+    }
+
+
+def _monster(monster: Monster, fighting: int) -> Json:
+    return {
+        "name": monster.name,
+        "size": monster.size,
+        "ac": monster.armor_class,
+        "hp": monster.hit_points,
+        "speed": monster.speed,
+        "cr": monster.challenge_rating,
+        "xp": monster.xp,
+        "initiative": monster.initiative_bonus,
+        "boss": monster.boss,
+        "legendary": [monster.legendary_actions, monster.legendary_resistances],
+        "actions": monster.actions,
+        "notes": monster.notes,
+        "fighting": fighting,
+    }

dndkit/web/__init__.py

@@ -0,0 +1,10 @@
+"""Web pages that follow the game live: the table screen, players' phones, the backstage.
+
+They run inside the MCP server's process (``server.web_pages``) and read the
+same campaign store and dice log as the tools, so a change shows at once.
+"""
+
+from dndkit.web.changes import Changes
+from dndkit.web.server import web_pages
+
+__all__ = ["Changes", "web_pages"]