dndkit 0.4.0__py3-none-any.whl

dndkit/game/journal.py

@@ -0,0 +1,47 @@
+"""Session notes and the campaign's adventure log."""
+
+from dndkit.models import AdventureEvent, Campaign, EventType, SessionNote
+from dndkit.text import normalize
+
+
+def add_session_note(campaign: Campaign, note: SessionNote) -> SessionNote:
+    """Record a session summary."""
+    campaign.sessions.append(note)
+    return note
+
+
+def sessions(campaign: Campaign) -> list[SessionNote]:
+    """Session notes in play order."""
+    return sorted(campaign.sessions, key=lambda note: (note.session_number, note.date))
+
+
+def add_event(campaign: Campaign, event: AdventureEvent) -> AdventureEvent:
+    """Log an event; it belongs to the current session unless it says otherwise."""
+    if event.session_number is None:
+        event.session_number = campaign.game_state.current_session
+    campaign.events.append(event)
+    return event
+
+
+def find_events(
+    campaign: Campaign,
+    *,
+    event_type: EventType | None = None,
+    search: str | None = None,
+    limit: int | None = None,
+) -> list[AdventureEvent]:
+    """Events newest first, filtered by type and by text in title, description or tags."""
+    events = campaign.events
+    if event_type is not None:
+        events = [e for e in events if e.event_type == event_type]
+    if search:
+        needle = normalize(search)
+        events = [
+            e
+            for e in events
+            if needle in normalize(e.title)
+            or needle in normalize(e.description)
+            or any(needle in normalize(tag) for tag in e.tags)
+        ]
+    events = sorted(events, key=lambda e: e.timestamp, reverse=True)
+    return events[:limit] if limit else events

dndkit/game/movement.py

@@ -0,0 +1,264 @@
+"""Moving a combatant on the battle map by the 5e rules (PHB ch. 9).
+
+A turn's movement is the creature's speed, doubled by Dash: 0 when grappled,
+restrained, stunned, paralyzed, petrified or unconscious, halved from
+exhaustion level 2 and 0 from level 5. A prone mover stands up first, for
+half its speed. A move to a square the mover cannot afford is refused; a move
+toward someone goes as far as it can. Forced movement (a shove, a spell)
+spends nothing and provokes nothing.
+"""
+
+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.game.pathing import Ground
+from dndkit.models import Campaign, Combatant
+
+HALTED = {"grappled", "restrained", "paralyzed", "petrified", "stunned", "unconscious"}
+DEFAULT_SPEED = 30
+
+
+@dataclass(frozen=True)
+class Move:
+    """What a move did, for the model to narrate."""
+
+    mover: Combatant
+    start: str
+    feet: int  # movement spent; for forced movement, distance moved
+    left: int  # movement left this turn
+    provoked: list[str]
+    stood_up: bool = False
+    forced: bool = False
+    short_of: tuple[str, int] | None = None  # a creature still out of reach, and how far
+
+
+@dataclass(frozen=True)
+class Order:
+    """Where a move goes: one of a square, toward someone, away from someone."""
+
+    to: str | None = None
+    toward: str | None = None
+    away_from: str | None = None
+    feet: int | None = None  # at most this far
+
+
+def speed(campaign: Campaign, combatant: Combatant) -> int:
+    """Walking speed now, conditions and exhaustion applied."""
+    character = campaign.characters.get(combatant.character_id or "")
+    if character is not None:
+        base, conditions, exhaustion = character.speed, character.conditions, character.exhaustion
+    else:
+        base = combatant.speed if combatant.speed is not None else DEFAULT_SPEED
+        conditions, exhaustion = combatant.conditions, 0
+    if HALTED & set(conditions) or exhaustion >= 5:
+        return 0
+    return base // 2 if exhaustion >= 2 else base
+
+
+def movement_left(campaign: Campaign, combatant: Combatant) -> int:
+    """Feet of movement left this turn."""
+    allowed = speed(campaign, combatant) * (2 if combatant.dashed else 1)
+    return max(0, allowed - combatant.movement_used)
+
+
+def move(
+    campaign: Campaign, who: str, order: Order, dash: bool, disengage: bool, forced: bool
+) -> Move:
+    """Move *who* as *order* says; the combatant's square and movement are updated."""
+    state = campaign.game_state
+    mover = combat.find(state, who)
+    start = battlefield.square_of(state, mover)
+    if start is None:
+        raise InvalidChangeError(f"{mover.name} is not on the map: place_tokens first.")
+    given = sum(target is not None for target in (order.to, order.toward, order.away_from))
+    if given != 1:
+        raise InvalidChangeError(
+            "Give only one of to, toward and away_from."
+            if given
+            else "Say where: to a square, toward someone or away_from someone."
+        )
+    if forced:
+        return _forced(campaign, mover, start, order)
+    mover.dashed = mover.dashed or dash
+    mover.disengaged = mover.disengaged or disengage
+    stood_up = _stand_up(campaign, mover)
+    if movement_left(campaign, mover) == 0:
+        raise InvalidChangeError(_stuck(campaign, mover))
+    ground = Ground(campaign, mover, provokes=not mover.disengaged)
+    found = pathing.routes(ground, start)
+    limit = movement_left(campaign, mover)
+    if order.feet is not None:
+        limit = min(limit, order.feet)
+    end, short_of = _destination(campaign, ground, found, start, order, limit)
+    route = pathing.path(found, end)
+    mover.position = grid.name(end)
+    mover.movement_used += found[end].feet
+    return Move(
+        mover=mover,
+        start=grid.name(start),
+        feet=found[end].feet,
+        left=movement_left(campaign, mover),
+        provoked=pathing.provoked_along(ground, route),
+        stood_up=stood_up,
+        short_of=short_of,
+    )
+
+
+def _destination(
+    campaign: Campaign,
+    ground: Ground,
+    found: dict[Square, pathing.Route],
+    start: Square,
+    order: Order,
+    limit: int,
+) -> tuple[Square, tuple[str, int] | None]:
+    if order.to is not None:
+        return _to_square(ground, found, order.to, limit), None
+    if order.toward is not None:
+        return _toward(campaign, ground, found, start, order.toward, limit)
+    away = _held(campaign, order.away_from or "")
+    reachable = [s for s, r in found.items() if r.feet <= limit and ground.standable(s)]
+    best = max(
+        [start, *reachable],
+        key=lambda s: (grid.steps_between(list(ground.squares(s)), away), -found[s].feet),
+    )
+    return best, None
+
+
+def _to_square(ground: Ground, found: dict[Square, pathing.Route], to: str, limit: int) -> Square:
+    target = grid.parse(to, ground.field)
+    side = grid.SIZE_SQUARES[ground.mover.size]
+    options = [
+        (target[0] - dx, target[1] - dy)
+        for dx in range(side)
+        for dy in range(side)
+        if (target[0] - dx, target[1] - dy) in found
+        and ground.standable((target[0] - dx, target[1] - dy))
+    ]
+    name = ground.mover.name
+    if not options:
+        raise InvalidChangeError(f"{name} cannot get to {to.upper()}: it is blocked or taken.")
+    best = min(options, key=lambda s: (found[s].feet, found[s].provocations))
+    if found[best].feet > limit:
+        raise InvalidChangeError(
+            f"{to.upper()} is {found[best].feet} feet of movement away; {name} has {limit} left. "
+            "Move toward it, or Dash."
+        )
+    return best
+
+
+def _toward(
+    campaign: Campaign,
+    ground: Ground,
+    found: dict[Square, pathing.Route],
+    start: Square,
+    toward: str,
+    limit: int,
+) -> tuple[Square, tuple[str, int] | None]:
+    target = combat.find(campaign.game_state, toward)
+    held = _held(campaign, toward)
+    reach = max(ground.mover.reach, grid.FEET)
+
+    def gap(s: Square) -> int:
+        return grid.feet_between(list(ground.squares(s)), held)
+
+    def _offset(s: Square) -> float:
+        mine = list(ground.squares(s))
+        return sum((_centre(mine, axis) - _centre(held, axis)) ** 2 for axis in (0, 1))
+
+    if gap(start) <= reach:
+        return start, None
+    near = [s for s in found if ground.standable(s) and gap(s) <= reach]
+    if near:  # cheapest first; of equals, the one facing the target squarely
+        goal = min(near, key=lambda s: (found[s].feet, found[s].provocations, _offset(s)))
+        if found[goal].feet <= limit:
+            return goal, None
+    else:  # walled off: head for the closest square there is
+        goal = min(found, key=lambda s: (gap(s), found[s].feet))
+    end = start
+    for square in pathing.path(found, goal):
+        if found[square].feet > limit:
+            break
+        if ground.standable(square):
+            end = square
+    return end, (target.name, gap(end))
+
+
+def _stuck(campaign: Campaign, mover: Combatant) -> str:
+    character = campaign.characters.get(mover.character_id or "")
+    conditions = set(character.conditions if character else mover.conditions)
+    halted = sorted(HALTED & conditions)
+    if halted:
+        return f"{mover.name} cannot move while {', '.join(halted)}."
+    if speed(campaign, mover) == 0:
+        return f"{mover.name} has a speed of 0."
+    return f"{mover.name} has no movement left this turn (Dash doubles it)."
+
+
+def _held(campaign: Campaign, name: str) -> list[Square]:
+    state = campaign.game_state
+    other = combat.find(state, name)
+    held = battlefield.footprint_of(state, other)
+    if held is None:
+        raise InvalidChangeError(f"{other.name} is not on the map: place_tokens first.")
+    return held
+
+
+def _stand_up(campaign: Campaign, mover: Combatant) -> bool:
+    character = campaign.characters.get(mover.character_id or "")
+    conditions = character.conditions if character else mover.conditions
+    if "prone" not in conditions:
+        return False
+    cost = speed(campaign, mover) // 2
+    if speed(campaign, mover) == 0 or movement_left(campaign, mover) < cost:
+        raise InvalidChangeError(f"{mover.name} is prone and lacks the movement to stand up.")
+    mover.movement_used += cost
+    standing = [c for c in conditions if c != "prone"]
+    if character is not None:
+        character.conditions = standing
+    else:
+        mover.conditions = standing
+    return True
+
+
+def _forced(campaign: Campaign, mover: Combatant, start: Square, order: Order) -> Move:
+    ground = Ground(campaign, mover, provokes=False)
+    if order.to is not None:
+        end = grid.parse(order.to, ground.field)
+        if not ground.standable(end):
+            raise InvalidChangeError(f"{mover.name} cannot be put on {order.to.upper()}.")
+    else:
+        source = _held(campaign, order.away_from or order.toward or "")
+        away = 1 if order.away_from is not None else -1
+        end = _push(ground, start, source, away, (order.feet or grid.FEET) // grid.FEET)
+    mover.position = grid.name(end)
+    moved = grid.steps_between([start], [end]) * grid.FEET
+    left = movement_left(campaign, mover)
+    return Move(
+        mover=mover, start=grid.name(start), feet=moved, left=left, provoked=[], forced=True
+    )
+
+
+def _push(ground: Ground, start: Square, source: list[Square], away: int, steps: int) -> Square:
+    mine = list(ground.squares(start))
+    dx, dy = (_sign(_centre(mine, axis) - _centre(source, axis)) * away for axis in (0, 1))
+    if not (dx or dy):
+        raise InvalidChangeError("They stand on the same spot: say where they go with to.")
+    here = start
+    for _ in range(steps):
+        there = (here[0] + dx, here[1] + dy)
+        if not ground.standable(there):  # a wall, the edge, or someone in the way
+            break
+        here = there
+    return here
+
+
+def _centre(squares: list[Square], axis: int) -> float:
+    values = [s[axis] for s in squares]
+    return (min(values) + max(values)) / 2
+
+
+def _sign(value: float) -> int:
+    return (value > 0) - (value < 0)

dndkit/game/pathing.py

@@ -0,0 +1,153 @@
+"""Routes across the battle map for one mover (PHB ch. 9, "Movement and Position").
+
+Entering a square costs 5 feet, diagonals included, and 10 in difficult
+terrain or in another creature's space. A mover passes through allies, and
+through foes only when two sizes apart; it never ends a move on anyone, and
+never squeezes diagonally between two walls. Leaving a foe's reach provokes
+an opportunity attack unless the mover Disengaged or is moved by force; of
+two routes as short, the one provoking fewer is taken.
+"""
+
+import heapq
+from dataclasses import dataclass
+
+from dndkit.game import battlefield, grid
+from dndkit.game.grid import Square
+from dndkit.models import Campaign, Combatant
+
+NO_REACTION = {"incapacitated", "paralyzed", "petrified", "stunned", "unconscious"}
+DIRECTIONS = [(dx, dy) for dx in (-1, 0, 1) for dy in (-1, 0, 1) if dx or dy]
+
+
+@dataclass(frozen=True)
+class Other:
+    """Another creature on the map, as the mover meets it."""
+
+    combatant: Combatant
+    squares: frozenset[Square]
+    passable: bool  # the mover may cross its space
+    threat_reach: int | None  # feet of reach in which leaving provokes; None: never
+
+
+@dataclass(frozen=True)
+class Route:
+    """The cheapest way found to a square."""
+
+    feet: int
+    provocations: int
+    previous: Square | None
+
+
+class Ground:
+    """The map as one mover sees it: walls, difficult terrain, the others."""
+
+    def __init__(
+        self, campaign: Campaign, mover: Combatant, provokes: bool, as_players_see: bool = False
+    ) -> None:
+        state = campaign.game_state
+        self.field = battlefield.require(state)
+        self.walls = battlefield.wall_squares(self.field)
+        self.difficult = battlefield.difficult_squares(self.field)
+        self.mover = mover
+        self.others = [
+            _meet(campaign, mover, other, held, provokes)
+            for other, held in battlefield.others(state, mover)
+            # The players' screens must not give a hidden foe away by a hole in the map.
+            if not (as_players_see and other.hidden and not battlefield.is_party(other))
+        ]
+
+    def squares(self, top_left: Square) -> frozenset[Square]:
+        """What the mover holds standing at *top_left*."""
+        return frozenset(grid.footprint(top_left, self.mover.size))
+
+    def crossable(self, top_left: Square) -> bool:
+        """Whether the mover may pass through *top_left*."""
+        held = self.squares(top_left)
+        if any(not grid.inside(s, self.field) or s in self.walls for s in held):
+            return False
+        return all(o.passable or not held & o.squares for o in self.others)
+
+    def standable(self, top_left: Square) -> bool:
+        """Whether the mover may end its move at *top_left*."""
+        held = self.squares(top_left)
+        return self.crossable(top_left) and not any(held & o.squares for o in self.others)
+
+    def step_feet(self, top_left: Square) -> int:
+        """What entering *top_left* costs."""
+        held = self.squares(top_left)
+        crowded = any(held & o.squares for o in self.others)
+        return 2 * grid.FEET if crowded or held & self.difficult else grid.FEET
+
+    def provoked(self, here: Square, there: Square) -> list[Combatant]:
+        """The foes whose reach the step from *here* to *there* leaves."""
+        before, after = list(self.squares(here)), list(self.squares(there))
+        return [
+            o.combatant
+            for o in self.others
+            if o.threat_reach is not None
+            and grid.feet_between(before, list(o.squares)) <= o.threat_reach
+            and grid.feet_between(after, list(o.squares)) > o.threat_reach
+        ]
+
+    def cuts_corner(self, here: Square, there: Square) -> bool:
+        """A diagonal step between two blocked squares."""
+        (x1, y1), (x2, y2) = here, there
+        if x1 == x2 or y1 == y2:
+            return False
+        return not self.crossable((x2, y1)) and not self.crossable((x1, y2))
+
+
+def routes(ground: Ground, start: Square) -> dict[Square, Route]:
+    """The cheapest route to every square the mover can reach (Dijkstra)."""
+    best = {start: Route(0, 0, None)}
+    queue = [(0, 0, start)]
+    while queue:
+        feet, provocations, here = heapq.heappop(queue)
+        if (feet, provocations) > (best[here].feet, best[here].provocations):
+            continue
+        for dx, dy in DIRECTIONS:
+            there = (here[0] + dx, here[1] + dy)
+            if not ground.crossable(there) or ground.cuts_corner(here, there):
+                continue
+            cost = (
+                feet + ground.step_feet(there),
+                provocations + len(ground.provoked(here, there)),
+            )
+            known = best.get(there)
+            if known is None or cost < (known.feet, known.provocations):
+                best[there] = Route(cost[0], cost[1], here)
+                heapq.heappush(queue, (cost[0], cost[1], there))
+    return best
+
+
+def path(found: dict[Square, Route], end: Square) -> list[Square]:
+    """The squares from the start to *end*, both included."""
+    squares = [end]
+    while (previous := found[squares[-1]].previous) is not None:
+        squares.append(previous)
+    return squares[::-1]
+
+
+def provoked_along(ground: Ground, squares: list[Square]) -> list[str]:
+    """Who gets an opportunity attack along *squares*, each named once."""
+    names: list[str] = []
+    for here, there in zip(squares, squares[1:], strict=False):
+        names += [c.name for c in ground.provoked(here, there) if c.name not in names]
+    return names
+
+
+def _meet(
+    campaign: Campaign, mover: Combatant, other: Combatant, held: list[Square], provokes: bool
+) -> Other:
+    hostile = battlefield.is_party(other) != battlefield.is_party(mover)
+    apart = abs(grid.SIZE_RANK[other.size] - grid.SIZE_RANK[mover.size]) >= 2
+    reacts = provokes and hostile and not other.reaction_used and can_react(campaign, other)
+    return Other(other, frozenset(held), not hostile or apart, other.reach if reacts else None)
+
+
+def can_react(campaign: Campaign, combatant: Combatant) -> bool:
+    """Whether *combatant* can take a reaction: conscious, not incapacitated."""
+    character = campaign.characters.get(combatant.character_id or "")
+    conditions = set(character.conditions if character else combatant.conditions)
+    hit_points = character.hit_points_current if character else combatant.hit_points
+    return not conditions & NO_REACTION and hit_points != 0

dndkit/game/proficiencies.py

@@ -0,0 +1,104 @@
+"""Skill and saving throw proficiencies (PHB ch. 7): the names players say, in
+English or French, and the bonus each gives (ability modifier + proficiency,
+twice the proficiency with Expertise)."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import rules
+from dndkit.game.tables import SKILL_ALIASES, SKILLS
+from dndkit.models import Character
+from dndkit.text import normalize
+
+
+@dataclass(frozen=True)
+class Proficiency:
+    """A proficient skill or saving throw and its bonus; None for a skill the rules
+    do not know (a sheet from elsewhere)."""
+
+    name: str
+    bonus: int | None
+
+
+def skill_name(text: str) -> str | None:
+    """ "stealth", "Discrétion" -> "Stealth"; None for anything else."""
+    wanted = normalize(text)
+    found = next((skill for skill in SKILLS if normalize(skill) == wanted), None)
+    return found or SKILL_ALIASES.get(wanted)
+
+
+def skills(names: Sequence[str]) -> list[str]:
+    """The skills *names* say, by their English names; one error lists the unknown."""
+    found = {name: skill_name(name) for name in names}
+    unknown = [name for name, skill in found.items() if skill is None]
+    if unknown:
+        raise InvalidChangeError(
+            f"Unknown skills: {', '.join(unknown)}. Skills (English or French names): "
+            f"{', '.join(SKILLS)}."
+        )
+    return list(dict.fromkeys(skill for skill in found.values() if skill))
+
+
+def saves(names: Sequence[str]) -> list[str]:
+    """The abilities *names* say ("DEX", "Sagesse"); one error lists the unknown."""
+    found = {name: rules.ability_name(name) for name in names}
+    unknown = [name for name, ability in found.items() if ability is None]
+    if unknown:
+        raise InvalidChangeError(f"Unknown saving throws: {', '.join(unknown)}; use STR to CHA.")
+    return list(dict.fromkeys(ability for ability in found.values() if ability))
+
+
+def expertise(names: Sequence[str], proficient: Sequence[str]) -> list[str]:
+    """The skills *names* say, each one among *proficient*: Expertise (a rogue's, a
+    bard's) doubles a proficiency the character has."""
+    chosen = skills(names)
+    have = {skill_name(name) for name in proficient}
+    missing = [skill for skill in chosen if skill not in have]
+    if missing:
+        raise InvalidChangeError(
+            f"Expertise doubles a proficiency, and {', '.join(missing)} is not among the "
+            "proficient skills: give it in skills too."
+        )
+    return chosen
+
+
+def jack_of_all_trades(character: Character) -> int:
+    """A bard's half proficiency, rounded down, on the checks it is not proficient in
+    (initiative included), from level 2."""
+    cls = character.character_class
+    if rules.class_key(cls.name) == "bard" and cls.level >= 2:
+        return character.proficiency_bonus // 2
+    return 0
+
+
+def skill_bonuses(character: Character) -> list[Proficiency]:
+    """Each proficient skill with its bonus, as the sheet lists them."""
+    experts = {skill_name(name) for name in character.skill_expertise}
+    shown: list[Proficiency] = []
+    for name in character.skill_proficiencies:
+        skill = skill_name(name)
+        ability = SKILLS[skill] if skill else None
+        times = 2 if skill and skill in experts else 1
+        shown.append(Proficiency(skill or name, _bonus(character, ability, times)))
+    return shown
+
+
+def save_bonuses(character: Character) -> list[Proficiency]:
+    """Each proficient saving throw with its bonus."""
+    abilities = [rules.ability_name(name) for name in character.saving_throw_proficiencies]
+    return [Proficiency(a, _bonus(character, a)) for a in abilities if a]
+
+
+def save_bonus(character: Character, ability: str) -> int:
+    """A saving throw's bonus: the modifier, plus proficiency where the sheet has it."""
+    score = character.abilities.get(ability)
+    proficient = ability in {rules.ability_name(n) for n in character.saving_throw_proficiencies}
+    return (score.mod if score else 0) + (character.proficiency_bonus if proficient else 0)
+
+
+def _bonus(character: Character, ability: str | None, times: int = 1) -> int | None:
+    if ability is None:
+        return None
+    score = character.abilities.get(ability)
+    return (score.mod if score else 0) + times * character.proficiency_bonus

dndkit/game/progression.py

@@ -0,0 +1,77 @@
+"""Experience and levels: awarding XP and levelling a character up (PHB ch. 1)."""
+
+from collections.abc import Sequence
+
+from dndkit.errors import InvalidChangeError
+from dndkit.game import characters, registry, rules, seating
+from dndkit.game.spellbook import describe_slots
+from dndkit.models import Campaign, Character, now
+
+
+def award_experience(campaign: Campaign, refs: Sequence[str], total_xp: int) -> list[str]:
+    """Split *total_xp* evenly between the named characters, else those at the table.
+
+    Without a roll call, the whole party is at the table (``seating``).
+    """
+    targets = (
+        registry.find_many(campaign.characters, refs, characters.KIND)
+        if refs
+        else seating.present_characters(campaign)
+    )
+    if not targets:
+        raise InvalidChangeError("There is no character to award experience to.")
+    share = rules.experience_per_character(total_xp, len(targets))
+    lines = [f"{total_xp} XP split between {len(targets)}: {share} each."]
+    for character in targets:
+        character.experience_points += share
+        character.updated_at = now()
+        line = f"{character.name}: {character.experience_points} XP"
+        reachable = rules.level_for_xp(character.experience_points)
+        if reachable > character.character_class.level:
+            line += f", enough for level {reachable} (use level_up)"
+        lines.append(line)
+    return lines
+
+
+def level_up(campaign: Campaign, ref: str, hit_die_roll: int | None) -> str:
+    """Raise a character one level: hit points, proficiency, hit dice, spell slots.
+
+    The hit point gain is the hit die roll (or the fixed average, half the die
+    plus one) plus the Constitution modifier, at least 1.
+    """
+    character = characters.find(campaign, ref)
+    cls = character.character_class
+    if cls.level >= 20:
+        raise InvalidChangeError(f"{character.name} is already level 20.")
+    die = rules.hit_die(cls.name)
+    if hit_die_roll is not None and not 1 <= hit_die_roll <= die:
+        raise InvalidChangeError(f"A d{die} roll is between 1 and {die}.")
+    roll = hit_die_roll if hit_die_roll is not None else die // 2 + 1
+    con = character.abilities["constitution"].mod if "constitution" in character.abilities else 0
+    gain = max(1, roll + con)
+    level = cls.level + 1
+    character.character_class = cls.model_copy(update={"level": level, "hit_dice": f"1d{die}"})
+    character.hit_points_max += gain
+    character.hit_points_current += gain
+    character.proficiency_bonus = rules.proficiency_bonus(level)
+    character.hit_dice_remaining = f"{min(level, characters.hit_dice_left(character) + 1)}d{die}"
+    slots_note = _update_slots(character, level)
+    character.updated_at = now()
+    source = "rolled" if hit_die_roll is not None else "average"
+    return (
+        f"{character.name} reaches level {level}: +{gain} HP ({source} {roll}, CON {con:+d}), "
+        f"HP {character.hit_points_current}/{character.hp_maximum}, "
+        f"proficiency +{character.proficiency_bonus}{slots_note}. "
+        f"Check the {cls.name} features gained at level {level}."
+    )
+
+
+def _update_slots(character: Character, level: int) -> str:
+    slots = rules.spell_slots_for(character.character_class.name, level)
+    if slots is None:
+        if rules.class_key(character.character_class.name) is None:
+            return "; unknown class, so spell slots are left as they were"
+        return ""
+    character.spell_slots_used = characters.slots_still_used(character, slots)
+    character.spell_slots = dict(slots)
+    return f", spell slots {describe_slots(character)}" if slots else ""