Skip to content

LevelUpResult

level_up_result

LevelUpResult dataclass

Represents the outcome of a single level-up operation.

This object provides a structured summary of the updated character state after advancing from one level to the next. It is returned by the level-up engine alongside the newly constructed Character instance.

The design mirrors the Character model: all fields are always present, and class-specific features are represented using neutral/default values rather than being omitted.

This ensures a consistent, predictable structure for consumers such as CLI output, logging, or UI rendering.

Attributes:

Name Type Description
class_name ClassName

The character's class.
race Race

The character's race.
old_level int

The character's level prior to leveling up.
new_level int

The character's level after leveling up.
hp_gained int

The number of hit points gained during this level-up.
new_hp_total int

The character's total hit points after applying the HP gain.
new_attack_bonus int

The updated attack bonus for the new level.
saving_throws SavingThrowData

The updated saving throw values for the new level.
new_spell_slots SpellSlots

Spell slots available at the new level. Non-spellcasting classes contain zero values.
thief_skills ThiefSkills

Thief skill percentages at the new level. Non-thief classes contain zero values.
turn_undead TurnUndead

Turn undead effectiveness at the new level. Non-cleric classes contain only None values.
Notes
  • This object represents the resulting state after leveling up, not a field-by-field delta.
  • Hit point gain is included explicitly, as it is a rolled value.
  • All attributes are always populated to maintain a uniform data shape.
Source code in src/rpgleveler/core/level_up_result.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
@dataclass
class LevelUpResult:
    """Represents the outcome of a single level-up operation.

    This object provides a structured summary of the updated character state
    after advancing from one level to the next. It is returned by the level-up
    engine alongside the newly constructed Character instance.

    The design mirrors the Character model: all fields are always present, and
    class-specific features are represented using neutral/default values rather
    than being omitted.

    This ensures a consistent, predictable structure for consumers such as CLI
    output, logging, or UI rendering.

    Attributes:
        class_name:
            The character's class.

        race:
            The character's race.

        old_level:
            The character's level prior to leveling up.

        new_level:
            The character's level after leveling up.

        hp_gained:
            The number of hit points gained during this level-up.

        new_hp_total:
            The character's total hit points after applying the HP gain.

        new_attack_bonus:
            The updated attack bonus for the new level.

        saving_throws:
            The updated saving throw values for the new level.

        new_spell_slots:
            Spell slots available at the new level.
            Non-spellcasting classes contain zero values.

        thief_skills:
            Thief skill percentages at the new level.
            Non-thief classes contain zero values.

        turn_undead:
            Turn undead effectiveness at the new level.
            Non-cleric classes contain only None values.

    Notes:
        - This object represents the resulting state after leveling up,
          not a field-by-field delta.
        - Hit point gain is included explicitly, as it is a rolled value.
        - All attributes are always populated to maintain a uniform data shape.
    """
    class_name: ClassName
    race: Race
    old_level: int
    new_level: int

    hp_gained: int
    new_hp_total: int

    new_attack_bonus: int
    saving_throws: SavingThrowData

    new_spell_slots: SpellSlots = SpellSlots(0,0,0,0,0)
    thief_skills: ThiefSkills = ThiefSkills(0,0,0,0,0,0,0,0)
    turn_undead: TurnUndead = TurnUndead(*(None,)*8)