From e34d4f967e1d576d3b4eaa176ba726bc3a23aa87 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Tue, 8 Jul 2025 10:09:37 -0400 Subject: [PATCH] docs: cancel PyPI wheel task and add future vision for Python extension architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task #70 Analysis: - Discovered fundamental incompatibility with PyPI distribution - McRogueFace embeds CPython rather than being loaded by it - Traditional wheels expect to extend existing Python interpreter - Current architecture is application-with-embedded-Python Decisions: - Cancelled PyPI wheel preparation as out of scope for Alpha - Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.) - Identified better distribution methods (installers, package managers) Added Future Vision: - Comprehensive plan for pure Python extension architecture - Would allow true "pip install mcrogueface" experience - Requires major refactoring to invert control flow - Python would drive main loop with C++ performance extensions - Unscheduled but documented as long-term possibility This clarifies the architectural boundaries and sets realistic expectations for distribution methods while preserving the vision of what McRogueFace could become with significant rework. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- ROADMAP.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 4 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 3b6b482..abb65d5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -290,9 +290,9 @@ Rendering Layer: **Goal**: Ready for the world ``` 1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08] -2. #86 - Add parameter documentation -3. #108 - Generate .pyi type stubs for IDE support -4. #70 - PyPI wheel preparation +2. ✅ #86 - Add parameter documentation [COMPLETED 2025-07-08] +3. ✅ #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08] +4. ❌ #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch] 5. API reference generator tool ``` @@ -535,4 +535,82 @@ Rendering Layer: --- -*Last Updated: 2025-07-05* +## 🔮 FUTURE VISION: Pure Python Extension Architecture + +### Concept: McRogueFace as a Traditional Python Package +**Status**: Unscheduled - Long-term vision +**Complexity**: Major architectural overhaul + +Instead of being a C++ application that embeds Python, McRogueFace could be redesigned as a pure Python extension module that can be installed via `pip install mcrogueface`. + +### Technical Approach +1. **Separate Core Engine from Python Embedding** + - Extract SFML rendering, audio, and input into C++ extension modules + - Remove embedded CPython interpreter + - Use Python's C API to expose functionality + +2. **Module Structure** + ``` + mcrfpy/ + ├── __init__.py # Pure Python coordinator + ├── _core.so # C++ rendering/game loop extension + ├── _sfml.so # SFML bindings + ├── _audio.so # Audio system bindings + └── engine.py # Python game engine logic + ``` + +3. **Inverted Control Flow** + - Python drives the main loop instead of C++ + - C++ extensions handle performance-critical operations + - Python manages game logic, scenes, and entity systems + +### Benefits +- **Standard Python Packaging**: `pip install mcrogueface` +- **Virtual Environment Support**: Works with venv, conda, poetry +- **Better IDE Integration**: Standard Python development workflow +- **Easier Testing**: Use pytest, standard Python testing tools +- **Cross-Python Compatibility**: Support multiple Python versions +- **Modular Architecture**: Users can import only what they need + +### Challenges +- **Major Refactoring**: Complete restructure of codebase +- **Performance Considerations**: Python-driven main loop overhead +- **Build Complexity**: Multiple extension modules to compile +- **Platform Support**: Need wheels for many platform/Python combinations +- **API Stability**: Would need careful design to maintain compatibility + +### Implementation Phases (If Pursued) +1. **Proof of Concept**: Simple SFML binding as Python extension +2. **Core Extraction**: Separate rendering from Python embedding +3. **Module Design**: Define clean API boundaries +4. **Incremental Migration**: Move systems one at a time +5. **Compatibility Layer**: Support existing games during transition + +### Example Usage (Future Vision) +```python +import mcrfpy +from mcrfpy import Scene, Frame, Sprite, Grid + +# Create game directly in Python +game = mcrfpy.Game(width=1024, height=768) + +# Define scenes using Python classes +class MainMenu(Scene): + def on_enter(self): + self.ui.append(Frame(100, 100, 200, 50)) + self.ui.append(Sprite("logo.png", x=400, y=100)) + + def on_keypress(self, key, pressed): + if key == "ENTER" and pressed: + self.game.set_scene("game") + +# Run the game +game.add_scene("menu", MainMenu()) +game.run() +``` + +This architecture would make McRogueFace a first-class Python citizen, following standard Python packaging conventions while maintaining high performance through C++ extensions. + +--- + +*Last Updated: 2025-07-08*