A flexible, code-first RPG framework for building turn-based games with support for procedural generation and AI-driven content.
Barebones RPG is a Python framework designed to be a foundation for creating RPG games. It provides all the essential systems needed for an RPG (combat, entities, items, quests, dialog, world management, etc.), but with no content - making it a perfect starting point for your own games.
The framework is code-first (Python classes and functions), fully extensible (hooks and events throughout), and supports both hand-crafted and procedurally generated content.
- Python 3.11+
# Install from PyPI
pip install barebones-rpg# Clone the repository
git clone https://github.com/PierceGov/barebones_rpg.git
cd barebones_rpg
# Install with uv (recommended)
uv sync --dev
# Or with pip
pip install -e ".[dev]"# Run the main example
uv run python main.py
# Or run specific examples
uv run python -m barebones_rpg.examples.simple_combat_example
uv run python -m barebones_rpg.examples.mini_rpg
uv run python -m barebones_rpg.examples.tile_based_example# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=barebones_rpgView the full documentation online
The documentation is also available locally in the sphinx_docs/ directory. To build and view:
./build_docs.sh
# Then open sphinx_docs/_build/html/index.htmlThe documentation includes:
- Getting Started Guide
- Core Concepts and Architecture
- Complete API Reference
- Step-by-Step Tutorials
- In-Depth Guides
- Example Breakdowns
from barebones_rpg import Game, GameConfig, Character, Enemy, Stats, Combat
# Create game
game = Game(GameConfig(title="My RPG"))
# Create characters
hero = Character(
name="Hero",
stats=Stats(strength=15, constitution=12, dexterity=10,
intelligence=8, charisma=10, base_max_hp=50, hp=100)
)
goblin = Enemy(
name="Goblin",
stats=Stats(strength=8, constitution=6, dexterity=12,
intelligence=5, charisma=5, base_max_hp=20, hp=30)
)
# Start combat
combat = Combat(
player_group=[hero],
enemy_group=[goblin],
events=game.events
)
combat.start()
# Example with custom AI
from barebones_rpg import AIInterface, AIContext
class SimpleAI(AIInterface):
def decide_action(self, context: AIContext) -> dict:
if context.nearby_entities:
return {"action": "attack", "target": context.nearby_entities[0]}
return {"action": "wait"}
# Assign AI directly to entity
goblin.ai = SimpleAI()See barebones_rpg/examples/ for complete working examples.
barebones_rpg/
├── core/ # Game engine, events, save/load
├── entities/ # Characters, NPCs, enemies, stats, AI
├── combat/ # Turn-based combat system
├── items/ # Items, inventory, equipment, loot
├── quests/ # Quest and objective tracking
├── dialog/ # Conversation trees
├── world/ # Maps, locations, tiles
├── rendering/ # Pygame renderer
├── loaders/ # Data loaders (JSON/YAML)
└── examples/ # Example games
Contributions are welcome!
MIT License - See LICENSE.md for details