McRogueFace Wiki

McRogueFace is a C++/Python 2D game engine for roguelikes and beyond, wrapping SFML, libtcod, and OpenGL behind a Python scripting layer. Current version: v0.2.5. Platforms: Linux, Windows (cross-compile), WebAssembly/Emscripten.

---

By System

Core engine systems and how they work:

• Grid-System - Multi-layer grids, chunk rendering, z-ordering, camera control
  • Grid-Rendering-Pipeline - Tile rendering internals
  • Grid-TCOD-Integration - libtcod FOV/pathfinding integration
  • Grid-Interaction-Patterns - Cell callbacks, click/hover handling
• Animation-System - 24+ easing functions, property locking, callbacks
• UI-Component-Hierarchy - Frame, Caption, Sprite, Grid, Entity, Arc, Circle, Line
  • UI-Widget-Patterns - Composition patterns for UI elements
• Input-and-Events - Key, MouseButton, InputState enums; click/hover/move callbacks
• Entity-Management - Grid-based entities, collections, sprite management
• AI-and-Pathfinding - FOV, A*, Dijkstra maps
• Procedural-Generation - DiscreteMap, HeightMap, NoiseSource, BSP, Tiled/LDtk import, Wang tiles
• Rendering-and-Visuals - Sprites, tilemaps, UI rendering
• Headless-Mode - Simulation control, automated testing, LLM agent integration
• Performance-and-Profiling - Profiler overlay, benchmarking, optimization

By Use Case

Practical guides for common tasks:

• Building a game - Start with Grid-System, Entity-Management, Input-and-Events
• Procedural levels - Procedural-Generation covers BSP, noise, Tiled/LDtk pipelines
• UI and menus - UI-Component-Hierarchy and UI-Widget-Patterns
• Animation and polish - Animation-System for easing, callbacks, property animation
• AI opponents - AI-and-Pathfinding for FOV, pathfinding algorithms
• Automated testing / LLM agents - Headless-Mode and Writing-Tests
• Performance tuning - Performance-and-Profiling and Performance-Optimization-Workflow

Development

Guides for extending the engine itself:

• Development-Workflow - Gitea-first workflow, issue tracking, wiki update procedures
• Adding-Python-Bindings - How to expose C++ types and methods to Python
• Python-Binding-Layer - Architecture of the C++/Python integration layer
• Writing-Tests - Test patterns, automation API, headless mode testing
• Performance-Optimization-Workflow - Measure-first optimization process
• LLM-Agent-Testbed-Architecture - Using McRogueFace as an LLM evaluation environment

Architecture and Planning

Design documents and project direction:

• Strategic-Direction - Project goals, development eras, priorities
• Issue-Roadmap - Current issue status by priority tier
• Design-Proposals - Index of architectural proposals
  • Proposal-Next-Generation-Grid-Entity-System - Grid/Entity system redesign

Quick Links

• API Reference: HTML docs - Complete API extracted from C++ docstrings
• Issue Tracker: Open Issues
• Repository: Source Code
• Build Guide: See CLAUDE.md in repository root for build instructions (Linux, Windows, Emscripten)

How to Use This Wiki

• System-focused: Start with the system pages above to understand engine architecture
• Use-case-focused: Follow the use case section for practical task-oriented navigation
• Issue-focused: The Issue-Roadmap links issues to relevant wiki pages
• Cross-referenced: Pages link to related systems, issues, and source files

This wiki is living documentation that evolves with the codebase. Issues reference wiki pages, and wiki pages reference current implementation files.

---

Last updated: 2026-02-07