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