McRogueFace/SFML_EXPOSURE_RESEARCH.md

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

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

• sf::Vector2f, sf::Vector2i
• sf::Color
• sf::Rect (FloatRect, IntRect)
• sf::VideoMode
• sf::Time, sf::Clock

Phase 2 - Graphics:

• sf::Texture (partial)
• 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:

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