200 lines
5.7 KiB
Markdown
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. |