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*