McRogueFace/SFML_3_MIGRATION_RESEARCH.md

257 lines
6.9 KiB
Markdown

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