McRogueFace/SFML_3_MIGRATION_RESEARCH.md

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

// 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<sf::Event::Closed>()) {
        window.close();
    } 
    else if (const auto* keyPressed = event->getIf<sf::Event::KeyPressed>()) {
        handleKey(keyPressed->code);
    }
}

3. Scoped Enumerations

// SFML 2.x
sf::Keyboard::A
sf::Mouse::Left

// SFML 3.0
sf::Keyboard::Key::A
sf::Mouse::Button::Left

4. Resource Loading

// 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

// 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

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

sf::Event event;
while (window && window->pollEvent(event)) {
    processEvent(event);
    if (event.type == sf::Event::Closed) {
        running = false;
    }
}

Current Key Mapping (ActionCode.h)

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