McRogueFace

Blame my wife for the name

A Python-powered 2D game engine for creating roguelike games, built with C++ and SFML.

• Core roguelike logic from libtcod: field of view, pathfinding
• Animate sprites with multiple frames. Smooth transitions for positions, sizes, zoom, and camera
• Simple GUI element system allows keyboard and mouse input, composition
• No compilation or installation necessary. The runtime is a full Python environment; "Zip And Ship"

Pre-Alpha Release Demo: my 7DRL 2025 entry "Crypt of Sokoban" - a prototype with buttons, boulders, enemies, and items.

Quick Start

Download:

• The entire McRogueFace visual framework:
  • Sprite: an image file or one sprite from a shared sprite sheet
  • Caption: load a font, display text
  • Frame: A rectangle; put other things on it to move or manage GUIs as modules
  • Grid: A 2D array of tiles with zoom + position control
  • Entity: Lives on a Grid, displays a sprite, and can have a perspective or move along a path
  • Animation: Change any property on any of the above over time

# Clone and build
git clone <wherever you found this repo>
cd McRogueFace
make

# Run the example game
cd build
./mcrogueface

Building from Source

For most users, pre-built releases are available. If you need to build from source:

Quick Build (with pre-built dependencies)

Download build_deps.tar.gz from the releases page, then:

git clone <repository-url> McRogueFace
cd McRogueFace
tar -xzf /path/to/build_deps.tar.gz
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Full Build (compiling all dependencies)

git clone --recursive <repository-url> McRogueFace
cd McRogueFace
# See BUILD_FROM_SOURCE.md for complete instructions

BUILD_FROM_SOURCE.md - Complete build guide including:

• System dependency installation
• Compiling SFML, Python, and libtcod-headless from source
• Creating build_deps archives for distribution
• Troubleshooting common build issues

System Requirements

• Linux: Debian/Ubuntu tested; other distros should work
• Windows: Supported (see build guide for details)
• macOS: Untested

Example: Creating a Simple Scene

import mcrfpy

# Create a new scene
intro = mcrfpy.Scene("intro")

# Add a text caption
caption = mcrfpy.Caption((50, 50), "Welcome to McRogueFace!")
caption.size = 48 
caption.fill_color = (255, 255, 255)

# Add to scene
intro.children.append(caption)

# Switch to the scene
intro.activate()

Documentation

📚 Developer Documentation

For comprehensive documentation about systems, architecture, and development workflows:

Project Wiki

Key wiki pages:

• Home - Documentation hub with multiple entry points
• Grid System - Three-layer grid architecture
• Python Binding System - C++/Python integration
• Performance and Profiling - Optimization tools
• Adding Python Bindings - Step-by-step binding guide
• Issue Roadmap - All open issues organized by system

📖 Development Guides

In the repository root:

• CLAUDE.md - Build instructions, testing guidelines, common tasks
• ROADMAP.md - Strategic vision and development phases
• roguelike_tutorial/ - Complete roguelike tutorial implementations

Build Requirements

• C++17 compiler (GCC 7+ or Clang 5+)
• CMake 3.14+
• Python 3.12+
• SFML 2.6
• Linux or Windows (macOS untested)

Project Structure

McRogueFace/
├── assets/        # Sprites, fonts, audio
├── build/         # Build output directory: zip + ship
│   ├─ (*)assets/  # (copied location of assets) 
│   ├─ (*)scripts/ # (copied location of src/scripts)
│   └─ lib/        # SFML, TCOD libraries,  Python + standard library / modules
├── deps/          # Python, SFML, and libtcod imports can be tossed in here to build
│   └─ platform/   # windows, linux subdirectories for OS-specific cpython config
├── docs/          # generated HTML, markdown docs
│   └─ stubs/      # .pyi files for editor integration
├── modules/       # git submodules, to build all of McRogueFace's dependencies from source
├── src/           # C++ engine source
│   └─ scripts/    # Python game scripts (copied during build)
└── tests/         # Automated test suite
└── tools/         # For the McRogueFace ecosystem: docs generation

If you are building McRogueFace to implement game logic or scene configuration in C++, you'll have to compile the project.

If you are writing a game in Python using McRogueFace, you only need to rename and zip/distribute the build directory.

Philosophy

• C++ every frame, Python every tick: All rendering data is handled in C++. Structure your UI and program animations in Python, and they are rendered without Python. All game logic can be written in Python.
• No Compiling Required; Zip And Ship: Implement your game objects with Python, zip up McRogueFace with your "game.py" to ship
• Built-in Roguelike Support: Dungeon generation, pathfinding, and field-of-view via libtcod
• Hands-Off Testing: PyAutoGUI-inspired event generation framework. All McRogueFace interactions can be performed headlessly via script: for software testing or AI integration
• Interactive Development: Python REPL integration for live game debugging. Use mcrogueface like a Python interpreter

Contributing

PRs will be considered! Please include explicit mention that your contribution is your own work and released under the MIT license in the pull request.

Issue Tracking

The project uses Gitea Issues for task tracking and bug reports. Issues are organized with labels:

• System labels (grid, animation, python-binding, etc.) - identify which codebase area
• Priority labels (tier1-active, tier2-foundation, tier3-future) - development timeline
• Type labels (Major Feature, Minor Feature, Bugfix, etc.) - effort and scope

See the Issue Roadmap on the wiki for organized view of all open tasks.

License

This project is licensed under the MIT License - see LICENSE file for details.

Acknowledgments

• Developed for 7-Day Roguelike 2023, 2024, 2025 - here's to many more
• Built with SFML, libtcod, and Python
• Inspired by David Churchill's COMP4300 game engine lectures