research: SFML exposure options analysis (#14)
- Analyzed current SFML 2.6.1 usage throughout codebase - Evaluated python-sfml (abandoned, only supports SFML 2.3.2) - Recommended direct integration as mcrfpy.sfml module - Created comprehensive SFML_EXPOSURE_RESEARCH.md with implementation plan - Identified opportunity to provide modern SFML 2.6+ Python bindings
This commit is contained in:
parent
f23aa784f2
commit
193294d3a7
2 changed files with 961 additions and 0 deletions
200
SFML_EXPOSURE_RESEARCH.md
Normal file
200
SFML_EXPOSURE_RESEARCH.md
Normal file
|
|
@ -0,0 +1,200 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue