Skip to content

Advancement

advancement

Character advancement and leveling rules for Basic Fantasy RPG.

This module defines the rules governing whether a character can level up, as well as the experience point (XP) thresholds required for progression.

These functions encapsulate the logic for determining level advancement eligibility and should be used by the level-up engine rather than accessing XP tables directly.

Structure
  • can_level_up: Determines if a character qualifies for the next level
  • get_next_level_threshold: Returns XP required for the next level
Notes
  • This module operates on XP progression rules only.
  • It does not modify character state.
  • All functions are deterministic and side-effect free.

can_level_up(character)

Determine whether a character qualifies to level up.

A character can level up if
  • Their current level is below the maximum supported level
  • Their experience points meet or exceed the threshold for the next level

Parameters:

Name Type Description Default
character Character

The character to evaluate.

 required

Returns:

Name Type Description
bool bool

True if the character can level up, False otherwise.
Source code in src/rpgleveler/engine/advancement.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def can_level_up(character: Character) -> bool:
    """
    Determine whether a character qualifies to level up.

    A character can level up if:
        - Their current level is below the maximum supported level
        - Their experience points meet or exceed the threshold for the next level

    Args:
        character:
            The character to evaluate.

    Returns:
        bool:
            True if the character can level up, False otherwise.
    """
    if is_max_level(character.level):
        return False

    required_xp = get_next_level_threshold(
        character.class_name, character.level)

    return character.xp >= required_xp

get_next_level_threshold(class_name, level)

Return the XP threshold required to reach the next level.

Parameters:

Name Type Description Default
class_name ClassName

The character class.

 required
level int

The character's current level.

 required

Returns:

Name Type Description
int int

The XP required to advance to the next level.

Raises:

Type Description
KeyError

If the class or level is not found in the XP tables.
Source code in src/rpgleveler/engine/advancement.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def get_next_level_threshold(class_name: ClassName, level: int) -> int:
    """
    Return the XP threshold required to reach the next level.

    Args:
        class_name:
            The character class.
        level:
            The character's current level.

    Returns:
        int:
            The XP required to advance to the next level.

    Raises:
        KeyError:
            If the class or level is not found in the XP tables.
    """
    if level >= MAX_LEVEL:
        raise ValueError(f"Level {level} is already at or above max level")

    next_level = level + 1
    return get_xp_requirement(class_name, next_level)

is_max_level(level)

Determine whether the given level is the maximum supported level.

Parameters:

Name Type Description Default
level int

The character's current level.

 required

Returns:

Name Type Description
bool bool

True if the level is at or above MAX_LEVEL, False otherwise.
Source code in src/rpgleveler/engine/advancement.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
def is_max_level(level: int) -> bool:
    """
    Determine whether the given level is the maximum supported level.

    Args:
        level:
            The character's current level.

    Returns:
        bool:
            True if the level is at or above MAX_LEVEL, False otherwise.
    """
    return level >= MAX_LEVEL