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
|
**Goal**: Ready for the world
|
||||||
```
|
```
|
||||||
1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
|
1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
|
||||||
2. #86 - Add parameter documentation
|
2. ✅ #86 - Add parameter documentation [COMPLETED 2025-07-08]
|
||||||
3. #108 - Generate .pyi type stubs for IDE support
|
3. ✅ #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08]
|
||||||
4. #70 - PyPI wheel preparation
|
4. ❌ #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch]
|
||||||
5. API reference generator tool
|
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