docs: cancel PyPI wheel task and add future vision for Python extension architecture
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 <noreply@anthropic.com>
This commit is contained in:
parent
d0e02d5b83
commit
e34d4f967e
86
ROADMAP.md
86
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*
|
||||
|
|
Loading…
Reference in New Issue