McRogueFace/SFML_EXPOSURE_RESEARCH.md

200 lines
5.7 KiB
Markdown

# SFML Exposure Research (#14)
## Executive Summary
After thorough research, I recommend **Option 3: Direct Integration** - implementing our own `mcrfpy.sfml` module with API compatibility to existing python-sfml bindings. This approach gives us full control while maintaining familiarity for developers who have used python-sfml.
## Current State Analysis
### McRogueFace SFML Usage
**Version**: SFML 2.6.1 (confirmed in `modules/SFML/include/SFML/Config.hpp`)
**Integration Level**: Moderate to Heavy
- SFML types appear in most header files
- Core rendering depends on `sf::RenderTarget`
- Event system uses `sf::Event` directly
- Input mapping uses SFML enums
**SFML Modules Used**:
- Graphics (sprites, textures, fonts, shapes)
- Window (events, keyboard, mouse)
- System (vectors, time, clocks)
- Audio (sound effects, music)
**Already Exposed to Python**:
- `mcrfpy.Color``sf::Color`
- `mcrfpy.Vector``sf::Vector2f`
- `mcrfpy.Font``sf::Font`
- `mcrfpy.Texture``sf::Texture`
### Python-SFML Status
**Official python-sfml (pysfml)**:
- Last version: 2.3.2 (supports SFML 2.3.2)
- Last meaningful update: ~2019
- Not compatible with SFML 2.6.1
- Project appears abandoned (domain redirects elsewhere)
- GitHub repo has 43 forks but no active maintained fork
**Alternatives**:
- No other major Python SFML bindings found
- Most alternatives were archived by 2021
## Option Analysis
### Option 1: Use Existing python-sfml
**Pros**:
- No development work needed
- Established API
**Cons**:
- Incompatible with SFML 2.6.1
- Would require downgrading to SFML 2.3.2
- Abandoned project (security/bug risks)
- Installation issues reported
**Verdict**: Not viable due to version incompatibility and abandonment
### Option 2: Fork and Update python-sfml
**Pros**:
- Leverage existing codebase
- Maintain API compatibility
**Cons**:
- Significant work to update from 2.3.2 to 2.6.1
- Cython complexity
- Maintenance burden of external codebase
- Still requires users to pip install separately
**Verdict**: High effort with limited benefit
### Option 3: Direct Integration (Recommended)
**Pros**:
- Full control over implementation
- Tight integration with McRogueFace
- No external dependencies
- Can expose exactly what we need
- Built-in module (no pip install)
- Can maintain API compatibility with python-sfml
**Cons**:
- Development effort required
- Need to maintain bindings
**Verdict**: Best long-term solution
## Implementation Plan for Direct Integration
### 1. Module Structure
```python
# Built-in module: mcrfpy.sfml
import mcrfpy.sfml as sf
# Maintain compatibility with python-sfml API
window = sf.RenderWindow(sf.VideoMode(800, 600), "My Window")
sprite = sf.Sprite()
texture = sf.Texture()
```
### 2. Priority Classes to Expose
**Phase 1 - Core Types** (Already partially done):
- [x] `sf::Vector2f`, `sf::Vector2i`
- [x] `sf::Color`
- [ ] `sf::Rect` (FloatRect, IntRect)
- [ ] `sf::VideoMode`
- [ ] `sf::Time`, `sf::Clock`
**Phase 2 - Graphics**:
- [x] `sf::Texture` (partial)
- [x] `sf::Font` (partial)
- [ ] `sf::Sprite` (full exposure)
- [ ] `sf::Text`
- [ ] `sf::Shape` hierarchy
- [ ] `sf::View`
- [ ] `sf::RenderWindow` (carefully managed)
**Phase 3 - Window/Input**:
- [ ] `sf::Event` and event types
- [ ] `sf::Keyboard` enums
- [ ] `sf::Mouse` enums
- [ ] `sf::Joystick`
**Phase 4 - Audio** (lower priority):
- [ ] `sf::SoundBuffer`
- [ ] `sf::Sound`
- [ ] `sf::Music`
### 3. Design Principles
1. **API Compatibility**: Match python-sfml's API where possible
2. **Memory Safety**: Use shared_ptr for resource management
3. **Thread Safety**: Consider GIL implications
4. **Integration**: Allow mixing with existing mcrfpy types
5. **Documentation**: Comprehensive docstrings
### 4. Technical Considerations
**Resource Sharing**:
- McRogueFace already manages SFML resources
- Need to share textures/fonts between mcrfpy and sfml modules
- Use the same underlying SFML objects
**Window Management**:
- McRogueFace owns the main window
- Expose read-only access or controlled modification
- Prevent users from closing/destroying the game window
**Event Handling**:
- Game engine processes events in main loop
- Need mechanism to expose events to Python safely
- Consider callback system or event queue
### 5. Implementation Phases
**Phase 1** (1-2 weeks):
- Create `mcrfpy.sfml` module structure
- Implement basic types (Vector, Color, Rect)
- Add comprehensive tests
**Phase 2** (2-3 weeks):
- Expose graphics classes
- Implement resource sharing with mcrfpy
- Create example scripts
**Phase 3** (2-3 weeks):
- Add window/input functionality
- Integrate with game event loop
- Performance optimization
**Phase 4** (1 week):
- Audio support
- Documentation
- PyPI packaging of mcrfpy.sfml separately
## Benefits of Direct Integration
1. **No Version Conflicts**: Always in sync with our SFML version
2. **Better Performance**: Direct C++ bindings without Cython overhead
3. **Selective Exposure**: Only expose what makes sense for game scripting
4. **Integrated Documentation**: Part of McRogueFace docs
5. **Future-Proof**: We control the implementation
## Migration Path for Users
Users familiar with python-sfml can easily migrate:
```python
# Old python-sfml code
import sfml as sf
# New McRogueFace code
import mcrfpy.sfml as sf
# Most code remains the same!
```
## Conclusion
Direct integration as `mcrfpy.sfml` provides the best balance of control, compatibility, and user experience. While it requires development effort, it ensures long-term maintainability and tight integration with McRogueFace's architecture.
The abandoned state of python-sfml actually presents an opportunity: we can provide a modern, maintained SFML binding for Python as part of McRogueFace, potentially attracting users who need SFML 2.6+ support.