A Python library + CLI for leveling up Basic Fantasy RPG characters.
rpgleveler provides a fully deterministic, rules-driven leveling engine
for Basic Fantasy RPG.
It handles:
- XP-based level advancement
- Hit point gains (including CON modifiers and racial caps)
- Attack bonus progression
- Saving throws
- Spell slots
- Thief skills
- Turn undead abilities
All game rules are implemented using immutable data tables and pure functions, making the system predictable, testable, and easy to extend.
- Pure functional design — no mutation of input characters
- Deterministic randomness via seeded dice rolls
- Modular architecture (engine, data, IO, CLI)
- Immutable rule tables for safety and correctness
- Fully tested with high coverage
- CLI + library support
rpgleveler character.jsonWith deterministic rolls:
rpgleveler character.json --seed 42Write output to a file:
rpgleveler character.json --out updated_character.jsonInstall the .whl from the latest release:
pip install https://github.com/retromatey/rpgleveler/releases/download/v0.1.0/rpgleveler-0.1.0-py3-none-any.whlNOTE: Replace v0.1.0 with the latest version from the
GitHub releases page.
git clone https://github.com/retromatey/rpgleveler.git
cd rpgleveler
pip install -e .[dev]Run checks:
ruff check .
mypy src
pytest --cov=rpgleveler --cov-report=term-missing
python -m buildfrom diceroller.core import DiceRoller
from rpgleveler import level_up, load_character
rng = DiceRoller(seed=42)
character = load_character("character.json")
new_character, result = level_up(character, rng=rng)
print(new_character.to_dict())rpgleveler
└── src
└── rpgleveler
├── cli # Command-line interface
├── core # Data models (Character, LevelUpResult)
├── data # Immutable rule tables
├── engine # Level-up logic
└── io # JSON import/export
Leveling up returns a new object:
new_character, result = level_up(character, rng=rng)All characters always include:
spell_slotsthief_skillsturn_undead
Even if unused — avoids branching logic and keeps everything consistent.
All randomness is injected:
DiceRoller(seed=42)This enables reproducible results and reliable tests.
Copyright Jason Tennant, 2026.
Distributed under the terms of the MIT license.
Basic Fantasy RPG is an open tabletop RPG by Chris Gonnerman and distributed under the terms of the Creative Commons Attribution-ShareAlike 4.0 International License.
This project is a fan-made utility and is not affiliated with the original authors or publishers.