McRogueFace Wiki

mcrf-meta -- objects: none | type: meta | status: current | verified: 0.2.8 (b6720f6)

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

Learning the engine? Tutorials, how-to guides, and worked examples live on the documentation site: mcrogueface.github.io.

Tracking work? Issue status by priority tier lives in ROADMAP.md and the issue tracker.

What This Wiki Holds

Two kinds of pages, and only these:

• Systems — normative architecture and contracts: how each engine system works, its invariants, and the promises the API makes.
• Plans — proposals and direction: design documents under consideration or in flight.

How-to and example content is deliberately not kept here; it belongs on the docs site.

---

Systems

Contracts

• API Stability Contract — compatibility promises that freeze at 1.0: Color/Vector value semantics, the edit() bulk-edit convention for writable views, subinterpreter scope
• Threading Model — the off-main-thread access contract

Engine Systems

• 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
• Entity Management — grid-based entities, collections, turn manager, behaviors
• Animation System — 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
• 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
• Python Binding Layer — architecture of the C++/Python integration layer

Engine Development

• Development Workflow — Gitea-first workflow, issue tracking, wiki update procedures
• Adding Python Bindings — exposing C++ types and methods to Python
• Writing Tests — test patterns, automation API, headless testing
• Performance Optimization Workflow — measure-first optimization process
• LLM Agent Testbed Architecture — McRogueFace as an LLM evaluation environment

Plans

• Design Proposals — index of proposals: status, process, evaluation criteria
  • Proposal: Next Generation Grid & Entity System — Grid/Entity redesign (partially implemented)
  • Proposal: Hybrid Scene Serialization — declarative scene-graph snapshots (#349)
  • Plan: Roguelike Tutorial Blueprint — tutorial series structure
  • Plan: mcrfpy Stdlib Widgets — standard widget library
• Strategic Direction — project goals, development eras, priorities

Quick Links

• Docs site: mcrogueface.github.io — tutorials, how-to guides, examples
• API Reference: docs/API_REFERENCE_DYNAMIC.md — generated from C++ docstrings; type stubs in stubs/mcrfpy.pyi
• Roadmap: ROADMAP.md — issue status by priority tier
• Issue Tracker: Open Issues
• Repository: Source Code
• Build Guide: CLAUDE.md in the repository root (Linux, Windows, Emscripten)

---

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

Last updated: 2026-07-11