# 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.