# SFML 3.0 Migration Research for McRogueFace ## Executive Summary SFML 3.0 was released on December 21, 2024, marking the first major version in 12 years. While it offers significant improvements in type safety, modern C++ features, and API consistency, migrating McRogueFace would require substantial effort. Given our plans for `mcrfpy.sfml`, I recommend **deferring migration to SFML 3.0** until after implementing the initial `mcrfpy.sfml` module with SFML 2.6.1. ## SFML 3.0 Overview ### Release Highlights - **Release Date**: December 21, 2024 - **Development**: 3 years, 1,100+ commits, 41 new contributors - **Major Feature**: C++17 support (now required) - **Audio Backend**: Replaced OpenAL with miniaudio - **Test Coverage**: Expanded to 57% - **New Features**: Scissor and stencil testing ### Key Breaking Changes #### 1. C++ Standard Requirements - **Minimum**: C++17 (was C++03) - **Compilers**: MSVC 16 (VS 2019), GCC 9, Clang 9, AppleClang 12 #### 2. Event System Overhaul ```cpp // SFML 2.x sf::Event event; while (window.pollEvent(event)) { switch (event.type) { case sf::Event::Closed: window.close(); break; case sf::Event::KeyPressed: handleKey(event.key.code); break; } } // SFML 3.0 while (const std::optional event = window.pollEvent()) { if (event->is()) { window.close(); } else if (const auto* keyPressed = event->getIf()) { handleKey(keyPressed->code); } } ``` #### 3. Scoped Enumerations ```cpp // SFML 2.x sf::Keyboard::A sf::Mouse::Left // SFML 3.0 sf::Keyboard::Key::A sf::Mouse::Button::Left ``` #### 4. Resource Loading ```cpp // SFML 2.x sf::Texture texture; if (!texture.loadFromFile("image.png")) { // Handle error } // SFML 3.0 try { sf::Texture texture("image.png"); } catch (const std::exception& e) { // Handle error } ``` #### 5. Geometry Changes ```cpp // SFML 2.x sf::FloatRect rect(left, top, width, height); // SFML 3.0 sf::FloatRect rect({left, top}, {width, height}); // Now uses position and size vectors ``` #### 6. CMake Changes ```cmake # SFML 2.x find_package(SFML 2.6 COMPONENTS graphics window system audio REQUIRED) target_link_libraries(app sfml-graphics sfml-window sfml-system sfml-audio) # SFML 3.0 find_package(SFML 3.0 COMPONENTS Graphics Window System Audio REQUIRED) target_link_libraries(app SFML::Graphics SFML::Window SFML::System SFML::Audio) ``` ## McRogueFace SFML Usage Analysis ### Current Usage Statistics - **SFML Version**: 2.6.1 - **Integration Level**: Moderate to Heavy - **Affected Files**: ~40+ source files ### Major Areas Requiring Changes #### 1. Event Handling (High Impact) - **Files**: `GameEngine.cpp`, `PyScene.cpp` - **Changes**: Complete rewrite of event loops - **Effort**: High #### 2. Enumerations (Medium Impact) - **Files**: `ActionCode.h`, all input handling - **Changes**: Update all keyboard/mouse enum references - **Effort**: Medium (mostly find/replace) #### 3. Resource Loading (Medium Impact) - **Files**: `PyTexture.cpp`, `PyFont.cpp`, `McRFPy_API.cpp` - **Changes**: Constructor-based loading with exception handling - **Effort**: Medium #### 4. Geometry (Low Impact) - **Files**: Various UI classes - **Changes**: Update Rect construction - **Effort**: Low #### 5. CMake Build System (Low Impact) - **Files**: `CMakeLists.txt` - **Changes**: Update find_package and target names - **Effort**: Low ### Code Examples from McRogueFace #### Current Event Loop (GameEngine.cpp) ```cpp sf::Event event; while (window && window->pollEvent(event)) { processEvent(event); if (event.type == sf::Event::Closed) { running = false; } } ``` #### Current Key Mapping (ActionCode.h) ```cpp {sf::Keyboard::Key::A, KEY_A}, {sf::Keyboard::Key::Left, KEY_LEFT}, {sf::Mouse::Left, MOUSEBUTTON_LEFT} ``` ## Impact on mcrfpy.sfml Module Plans ### Option 1: Implement with SFML 2.6.1 First (Recommended) **Pros**: - Faster initial implementation - Stable, well-tested SFML version - Can provide value immediately - Migration can be done later **Cons**: - Will require migration work later - API might need changes for SFML 3.0 ### Option 2: Wait and Implement with SFML 3.0 **Pros**: - Future-proof implementation - Modern C++ features - No migration needed later **Cons**: - Delays `mcrfpy.sfml` implementation - SFML 3.0 is very new (potential bugs) - Less documentation/examples available ### Option 3: Dual Support **Pros**: - Maximum flexibility - Gradual migration path **Cons**: - Significant additional complexity - Maintenance burden - Conditional compilation complexity ## Migration Strategy Recommendation ### Phase 1: Current State (Now) 1. Continue with SFML 2.6.1 2. Implement `mcrfpy.sfml` module as planned 3. Design module API to minimize future breaking changes ### Phase 2: Preparation (3-6 months) 1. Monitor SFML 3.0 stability and adoption 2. Create migration branch for testing 3. Update development environment to C++17 ### Phase 3: Migration (6-12 months) 1. Migrate McRogueFace core to SFML 3.0 2. Update `mcrfpy.sfml` to match 3. Provide migration guide for users ### Phase 4: Deprecation (12-18 months) 1. Deprecate SFML 2.6.1 support 2. Focus on SFML 3.0 features ## Specific Migration Tasks ### Prerequisites - [ ] Update to C++17 compatible compiler - [ ] Update CMake to 3.16+ - [ ] Review all SFML usage locations ### Core Changes - [ ] Rewrite all event handling loops - [ ] Update all enum references - [ ] Convert resource loading to constructors - [ ] Update geometry construction - [ ] Update CMake configuration ### mcrfpy.sfml Considerations - [ ] Design API to be version-agnostic where possible - [ ] Use abstraction layer for version-specific code - [ ] Document version requirements clearly ## Risk Assessment ### High Risk Areas 1. **Event System**: Complete paradigm shift 2. **Exception Handling**: New resource loading model 3. **Third-party Dependencies**: May not support SFML 3.0 yet ### Medium Risk Areas 1. **Performance**: New implementations may differ 2. **Platform Support**: New version may have issues 3. **Documentation**: Less community knowledge ### Low Risk Areas 1. **Basic Rendering**: Core concepts unchanged 2. **CMake**: Straightforward updates 3. **Enums**: Mechanical changes ## Conclusion While SFML 3.0 offers significant improvements, the migration effort is substantial. Given that: 1. SFML 3.0 is very new (released December 2024) 2. McRogueFace has heavy SFML integration 3. We plan to implement `mcrfpy.sfml` soon 4. The event system requires complete rewriting **I recommend deferring SFML 3.0 migration** until after successfully implementing `mcrfpy.sfml` with SFML 2.6.1. This allows us to: - Deliver value sooner with `mcrfpy.sfml` - Learn from early adopters of SFML 3.0 - Design our module API with migration in mind - Migrate when SFML 3.0 is more mature The migration should be revisited in 6-12 months when SFML 3.0 has proven stability and wider adoption.