# 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
```python
# 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):
- [x] `sf::Vector2f`, `sf::Vector2i`
- [x] `sf::Color`
- [ ] `sf::Rect` (FloatRect, IntRect)
- [ ] `sf::VideoMode`
- [ ] `sf::Time`, `sf::Clock`

**Phase 2 - Graphics**:
- [x] `sf::Texture` (partial)
- [x] `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:
```python
# 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.