research: SFML exposure options analysis (#14)
- Analyzed current SFML 2.6.1 usage throughout codebase - Evaluated python-sfml (abandoned, only supports SFML 2.3.2) - Recommended direct integration as mcrfpy.sfml module - Created comprehensive SFML_EXPOSURE_RESEARCH.md with implementation plan - Identified opportunity to provide modern SFML 2.6+ Python bindings
This commit is contained in:
parent
f23aa784f2
commit
193294d3a7
|
|
@ -0,0 +1,761 @@
|
|||
# Alpha Streamline 2 Work Log
|
||||
|
||||
## Phase 5: Window/Scene Architecture
|
||||
|
||||
### Task: SFML Exposure Research (#14)
|
||||
|
||||
**Status**: Research Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Research Summary**:
|
||||
1. Analyzed current SFML usage in McRogueFace:
|
||||
- Using SFML 2.6.1 (built from source in modules/SFML)
|
||||
- Moderate to heavy integration with SFML types throughout codebase
|
||||
- Already exposing Color, Vector, Font, and Texture to Python
|
||||
- All rendering, input, and audio systems depend on SFML
|
||||
|
||||
2. Evaluated python-sfml (pysfml):
|
||||
- Last version 2.3.2 only supports SFML 2.3.2 (incompatible with our 2.6.1)
|
||||
- Project appears abandoned since ~2019
|
||||
- No viable maintained alternatives found
|
||||
- Installation issues widely reported
|
||||
|
||||
3. Recommendation: **Direct Integration**
|
||||
- Implement `mcrfpy.sfml` as built-in module
|
||||
- Maintain API compatibility with python-sfml where sensible
|
||||
- Gives full control and ensures version compatibility
|
||||
- Can selectively expose only what makes sense for game scripting
|
||||
|
||||
**Key Findings**:
|
||||
- Direct integration allows resource sharing between mcrfpy and sfml modules
|
||||
- Can prevent unsafe operations (e.g., closing the game window)
|
||||
- Opportunity to provide modern SFML 2.6+ Python bindings
|
||||
- Implementation phases outlined in SFML_EXPOSURE_RESEARCH.md
|
||||
|
||||
**Result**: Created comprehensive research document recommending direct integration approach with detailed implementation plan.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Visibility & Performance
|
||||
|
||||
### Task 3: Basic Profiling/Metrics (#104)
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Implementation**:
|
||||
1. Added ProfilingMetrics struct to GameEngine:
|
||||
- Frame time tracking (current and 60-frame average)
|
||||
- FPS calculation from average frame time
|
||||
- Draw call counting per frame
|
||||
- UI element counting (total and visible)
|
||||
- Runtime tracking
|
||||
|
||||
2. Integrated metrics collection:
|
||||
- GameEngine::run() updates frame time metrics each frame
|
||||
- PyScene::render() counts UI elements and draw calls
|
||||
- Metrics reset at start of each frame
|
||||
|
||||
3. Exposed metrics to Python:
|
||||
- Added mcrfpy.getMetrics() function
|
||||
- Returns dictionary with all metrics
|
||||
- Accessible from Python scripts for monitoring
|
||||
|
||||
**Features**:
|
||||
- Real-time frame time and FPS tracking
|
||||
- 60-frame rolling average for stable FPS display
|
||||
- Per-frame draw call counting
|
||||
- UI element counting (total vs visible)
|
||||
- Total runtime tracking
|
||||
- Current frame counter
|
||||
|
||||
**Testing**:
|
||||
- Created test scripts (test_metrics.py, test_metrics_simple.py)
|
||||
- Verified metrics API is accessible from Python
|
||||
- Note: Metrics are only populated after game loop starts
|
||||
|
||||
**Result**: Basic profiling system ready for performance monitoring and optimization.
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Click Handling Improvements
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Implementation**:
|
||||
1. Fixed UIFrame coordinate transformation:
|
||||
- Now correctly subtracts parent position for child coordinates (was adding)
|
||||
- Checks children in reverse order (highest z-index first)
|
||||
- Checks bounds first for optimization
|
||||
- Invisible elements are skipped entirely
|
||||
|
||||
2. Fixed Scene click handling z-order:
|
||||
- PyScene::do_mouse_input now sorts elements by z-index (highest first)
|
||||
- Click events stop at the first handler found
|
||||
- Ensures top-most elements receive clicks first
|
||||
|
||||
3. Implemented UIGrid entity clicking:
|
||||
- Transforms screen coordinates to grid coordinates
|
||||
- Checks entities in reverse order
|
||||
- Returns entity sprite as click target (entities delegate to their sprite)
|
||||
- Accounts for grid zoom and center position
|
||||
|
||||
**Features**:
|
||||
- Correct z-order click priority (top elements get clicks first)
|
||||
- Click transparency (elements without handlers don't block clicks)
|
||||
- Proper coordinate transformation for nested frames
|
||||
- Grid entity click detection with coordinate transformation
|
||||
- Invisible elements don't receive or block clicks
|
||||
|
||||
**Testing**:
|
||||
- Created comprehensive test suite (test_click_handling.py)
|
||||
- Tests cannot run in headless mode due to PyScene::do_mouse_input early return
|
||||
- Manual testing would be required to verify functionality
|
||||
|
||||
**Result**: Click handling now correctly respects z-order, coordinate transforms, and visibility.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Name System Implementation (#39/40/41)
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Implementation**:
|
||||
1. Added `std::string name` member to UIDrawable base class
|
||||
2. Implemented get_name/set_name static methods in UIDrawable for Python bindings
|
||||
3. Added name property to all UI class Python getsetters:
|
||||
- Frame, Caption, Sprite, Grid: Use UIDrawable::get_name/set_name directly
|
||||
- Entity: Special handlers that delegate to entity->sprite.name
|
||||
4. Implemented find() and findAll() functions in McRFPy_API:
|
||||
- find(name, scene=None) - Returns first element with exact name match
|
||||
- findAll(pattern, scene=None) - Returns list of elements matching pattern (supports * wildcards)
|
||||
- Both functions search recursively through Frame children and Grid entities
|
||||
- Can search current scene or specific named scene
|
||||
|
||||
**Features**:
|
||||
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name property
|
||||
- Names default to empty string ""
|
||||
- Names support Unicode characters
|
||||
- find() returns None if no match found
|
||||
- findAll() returns empty list if no matches
|
||||
- Wildcard patterns: "*_frame" matches "main_frame", "sidebar_frame"
|
||||
- Searches nested elements: Frame children and Grid entities
|
||||
|
||||
**Testing**:
|
||||
- Created comprehensive test suite (test_name_property.py, test_find_functions.py)
|
||||
- All tests pass for name property on all UI types
|
||||
- All tests pass for find/findAll functionality including wildcards
|
||||
|
||||
**Result**: Complete name-based element finding system ready for use.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundation Stabilization
|
||||
|
||||
### Task #7: Audit Unsafe Constructors
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Findings**:
|
||||
- All UI classes (UIFrame, UICaption, UISprite, UIGrid, UIEntity) have no-argument constructors
|
||||
- These are required by the Python C API's two-phase initialization pattern:
|
||||
- `tp_new` creates a default C++ object with `std::make_shared<T>()`
|
||||
- `tp_init` initializes the object with actual values
|
||||
- This pattern ensures proper shared_ptr lifetime management and exception safety
|
||||
|
||||
**Decision**: Keep the no-argument constructors but ensure they're safe:
|
||||
1. Initialize all members to safe defaults
|
||||
2. Set reasonable default sizes (0,0) and positions (0,0)
|
||||
3. Ensure no uninitialized pointers
|
||||
|
||||
**Code Changes**:
|
||||
- UIFrame: Already safe - initializes outline, children, position, and size
|
||||
- UISprite: Empty constructor - needs safety improvements
|
||||
- UIGrid: Empty constructor - needs safety improvements
|
||||
- UIEntity: Empty constructor with TODO comment - needs safety improvements
|
||||
- UICaption: Uses compiler default - needs explicit constructor with safe defaults
|
||||
|
||||
**Recommendation**: Rather than remove these constructors (which would break Python bindings), we should ensure they initialize all members to safe, predictable values.
|
||||
|
||||
**Implementation**:
|
||||
1. Added safe default constructors for all UI classes:
|
||||
- UISprite: Initializes sprite_index=0, ptex=nullptr, position=(0,0), scale=(1,1)
|
||||
- UIGrid: Initializes all dimensions to 0, creates empty entity list, minimal render texture
|
||||
- UIEntity: Initializes self=nullptr, grid=nullptr, position=(0,0), collision_pos=(0,0)
|
||||
- UICaption: Initializes empty text, position=(0,0), size=12, white color
|
||||
|
||||
2. Fixed Python init functions to accept no arguments:
|
||||
- Changed PyArg_ParseTupleAndKeywords format strings to make all args optional (using |)
|
||||
- Properly initialized all variables that receive optional arguments
|
||||
- Added NULL checks for optional PyObject* parameters
|
||||
- Set sensible defaults when no arguments provided
|
||||
|
||||
**Result**: All UI classes can now be safely instantiated with no arguments from both C++ and Python.
|
||||
|
||||
---
|
||||
|
||||
### Task #71: Create Python Base Class _Drawable
|
||||
|
||||
**Status**: In Progress
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Implementation**:
|
||||
1. Created PyDrawable.h/cpp with Python type for _Drawable base class
|
||||
2. Added properties to UIDrawable base class:
|
||||
- visible (bool) - #87
|
||||
- opacity (float) - #88
|
||||
3. Added virtual methods to UIDrawable:
|
||||
- get_bounds() - returns sf::FloatRect - #89
|
||||
- move(dx, dy) - relative movement - #98
|
||||
- resize(w, h) - absolute sizing - #98
|
||||
4. Implemented these methods in all derived classes:
|
||||
- UIFrame: Uses box position/size
|
||||
- UICaption: Uses text bounds, resize is no-op
|
||||
- UISprite: Uses sprite bounds, resize scales sprite
|
||||
- UIGrid: Uses box position/size, recreates render texture
|
||||
5. Updated render methods to check visibility and apply opacity
|
||||
6. Registered PyDrawableType in McRFPy_API module initialization
|
||||
|
||||
**Decision**: While the C++ implementation is complete, updating the Python type hierarchy to inherit from PyDrawable would require significant refactoring of the existing getsetters. This is deferred to a future phase to avoid breaking existing code. The properties and methods are implemented at the C++ level and will take effect when rendering.
|
||||
|
||||
**Result**:
|
||||
- C++ UIDrawable base class now has visible (bool) and opacity (float) properties
|
||||
- All derived classes implement get_bounds(), move(dx,dy), and resize(w,h) methods
|
||||
- Render methods check visibility and apply opacity where supported
|
||||
- Python _Drawable type created but not yet used as base class
|
||||
|
||||
---
|
||||
|
||||
### Task #101: Standardize Default Positions
|
||||
|
||||
**Status**: Completed (already implemented)
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Findings**: All UI classes (Frame, Caption, Sprite, Grid) already default to position (0,0) when position arguments are not provided. This was implemented as part of the safe constructor work in #7.
|
||||
|
||||
---
|
||||
|
||||
### Task #38: Frame Children Parameter
|
||||
|
||||
**Status**: In Progress
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Allow Frame initialization with children parameter: `Frame(x, y, w, h, children=[...])`
|
||||
|
||||
**Implementation**:
|
||||
1. Added `children` parameter to Frame.__init__ keyword arguments
|
||||
2. Process children after frame initialization
|
||||
3. Validate each child is a Frame, Caption, Sprite, or Grid
|
||||
4. Add valid children to frame's children collection
|
||||
5. Set children_need_sort flag for z-index sorting
|
||||
|
||||
**Result**: Frames can now be initialized with their children in a single call, making UI construction more concise.
|
||||
|
||||
---
|
||||
|
||||
### Task #42: Click Handler in __init__
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Allow setting click handlers during initialization for all UI elements
|
||||
|
||||
**Implementation**:
|
||||
1. Added `click` parameter to __init__ methods for Frame, Caption, and Sprite
|
||||
2. Validates that click handler is callable (or None)
|
||||
3. Registers click handler using existing click_register() method
|
||||
4. Works alongside other initialization parameters
|
||||
|
||||
**Changes Made**:
|
||||
- UIFrame: Added click parameter to init, validates and registers handler
|
||||
- UICaption: Added click parameter to init, validates and registers handler
|
||||
- UISprite: Added click parameter to init, validates and registers handler
|
||||
- UIGrid: Already had click parameter support
|
||||
|
||||
**Result**: All UI elements can now have click handlers set during initialization, making interactive UI creation more concise. Lambda functions and other callables work correctly.
|
||||
|
||||
---
|
||||
|
||||
### Task #90: Grid Size Tuple Support
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Allow Grid to accept grid_size=(width, height) as an alternative to separate grid_x, grid_y arguments
|
||||
|
||||
**Implementation**:
|
||||
1. Added `grid_size` keyword parameter to Grid.__init__
|
||||
2. Accepts either tuple or list of two integers
|
||||
3. If provided, grid_size overrides any grid_x/grid_y values
|
||||
4. Maintains backward compatibility with positional grid_x, grid_y arguments
|
||||
|
||||
**Changes Made**:
|
||||
- Modified UIGrid::init to use PyArg_ParseTupleAndKeywords
|
||||
- Added parsing logic for grid_size parameter
|
||||
- Validates that grid_size contains exactly 2 integers
|
||||
- Falls back to positional arguments if keywords not used
|
||||
|
||||
**Test Results**:
|
||||
- grid_size tuple works correctly
|
||||
- grid_size list works correctly
|
||||
- Traditional grid_x, grid_y still works
|
||||
- grid_size properly overrides grid_x, grid_y if both provided
|
||||
- Proper error handling for invalid grid_size values
|
||||
|
||||
**Result**: Grid initialization is now more flexible, allowing either `Grid(10, 15)` or `Grid(grid_size=(10, 15))` syntax
|
||||
|
||||
---
|
||||
|
||||
### Task #19: Sprite Texture Swapping
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Verify and document sprite texture swapping functionality
|
||||
|
||||
**Findings**:
|
||||
- Sprite texture swapping was already implemented via the `texture` property
|
||||
- The getter and setter were already exposed in the Python API
|
||||
- `setTexture()` method preserves sprite position and scale
|
||||
|
||||
**Implementation Details**:
|
||||
- UISprite::get_texture returns the texture via pyObject()
|
||||
- UISprite::set_texture validates the input is a Texture instance
|
||||
- The C++ setTexture method updates the sprite with the new texture
|
||||
- Sprite index can be optionally updated when setting texture
|
||||
|
||||
**Test Results**:
|
||||
- Texture swapping works correctly
|
||||
- Position and scale are preserved during texture swap
|
||||
- Type validation prevents assigning non-Texture objects
|
||||
- Sprite count changes verify texture was actually swapped
|
||||
|
||||
**Result**: Sprite texture swapping is fully functional. Sprites can change their texture at runtime while preserving position and scale.
|
||||
|
||||
---
|
||||
|
||||
### Task #52: Grid Skip Out-of-Bounds Entities
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Add bounds checking to skip rendering entities outside the visible grid area for performance
|
||||
|
||||
**Implementation**:
|
||||
1. Added visibility bounds check in UIGrid::render() entity loop
|
||||
2. Calculate visible bounds based on left_edge, top_edge, width_sq, height_sq
|
||||
3. Skip entities outside bounds with 1 cell margin for partially visible entities
|
||||
4. Bounds check considers zoom and pan settings
|
||||
|
||||
**Code Changes**:
|
||||
```cpp
|
||||
// Check if entity is within visible bounds (with 1 cell margin)
|
||||
if (e->position.x < left_edge - 1 || e->position.x >= left_edge + width_sq + 1 ||
|
||||
e->position.y < top_edge - 1 || e->position.y >= top_edge + height_sq + 1) {
|
||||
continue; // Skip this entity
|
||||
}
|
||||
```
|
||||
|
||||
**Test Results**:
|
||||
- Entities outside view bounds are successfully skipped
|
||||
- Performance improvement when rendering grids with many entities
|
||||
- Zoom and pan correctly affect culling bounds
|
||||
- 1 cell margin ensures partially visible entities still render
|
||||
|
||||
**Result**: Grid rendering now skips out-of-bounds entities, improving performance for large grids with many entities. This is especially beneficial for games with large maps.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Entity Lifecycle Management
|
||||
|
||||
### Task #30: Entity.die() Method
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Implement Entity.die() method to remove entity from its grid
|
||||
|
||||
**Implementation**:
|
||||
1. Added die() method to UIEntity class
|
||||
2. Method finds and removes entity from grid's entity list
|
||||
3. Clears entity's grid reference after removal
|
||||
4. Safe to call multiple times (no-op if not on grid)
|
||||
|
||||
**Code Details**:
|
||||
- UIEntityCollection::append already sets entity->grid when added
|
||||
- UIEntityCollection::remove already clears grid reference when removed
|
||||
- die() method uses std::find_if to locate entity in grid's list
|
||||
- Uses shared_ptr comparison to find correct entity
|
||||
|
||||
**Test Results**:
|
||||
- Basic die() functionality works correctly
|
||||
- Safe to call on entities not in a grid
|
||||
- Works correctly with multiple entities
|
||||
- Can be called multiple times safely
|
||||
- Works in loops over entity collections
|
||||
- Python references remain valid after die()
|
||||
|
||||
**Result**: Entities can now remove themselves from their grid with a simple die() call. This enables cleaner entity lifecycle management in games.
|
||||
|
||||
---
|
||||
|
||||
### Standardized Position Arguments
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Standardize position argument handling across all UI classes for consistency
|
||||
|
||||
**Problem**:
|
||||
- Caption expected pos first, not x, y
|
||||
- Grid didn't use keywords
|
||||
- Grid.at() didn't accept tuple format
|
||||
- Inconsistent position argument formats across classes
|
||||
|
||||
**Implementation**:
|
||||
1. Created PyPositionHelper.h with standardized position parsing utilities
|
||||
2. Updated Grid.at() to accept: (x, y), ((x,y)), x=x, y=y, pos=(x,y)
|
||||
3. Updated Caption to accept: (x, y), ((x,y)), x=x, y=y, pos=(x,y)
|
||||
4. Ensured Grid supports keyword arguments
|
||||
5. Maintained backward compatibility for all formats
|
||||
|
||||
**Standardized Formats**:
|
||||
All position arguments now support:
|
||||
- `(x, y)` - two positional arguments
|
||||
- `((x, y))` - single tuple argument
|
||||
- `x=x, y=y` - keyword arguments
|
||||
- `pos=(x,y)` - pos keyword with tuple
|
||||
- `pos=Vector` - pos keyword with Vector object
|
||||
|
||||
**Classes Updated**:
|
||||
- Grid.at() - Now accepts all standard position formats
|
||||
- Caption - Now accepts x,y in addition to pos
|
||||
- Grid - Keywords fully supported
|
||||
- Frame - Already supported both formats
|
||||
- Sprite - Already supported both formats
|
||||
- Entity - Uses pos keyword
|
||||
|
||||
**Test Results**:
|
||||
- All position formats work correctly
|
||||
- Backward compatibility maintained
|
||||
- Consistent error messages across classes
|
||||
|
||||
**Result**: All UI classes now have consistent, flexible position argument handling. This improves API usability and reduces confusion when working with different UI elements.
|
||||
|
||||
**Update**: Extended standardization to Frame, Sprite, and Entity:
|
||||
- Frame already had dual format support, improved with pos keyword override
|
||||
- Sprite already had dual format support, improved with pos keyword override
|
||||
- Entity now supports x, y arguments in addition to pos (was previously pos-only)
|
||||
- No blockers found - all classes benefit from standardization
|
||||
- PyPositionHelper could be used for even cleaner implementation in future
|
||||
|
||||
---
|
||||
|
||||
### Bug Fix: Click Handler Segfault
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Issue**: Accessing the `click` property on UI elements that don't have a click handler set caused a segfault.
|
||||
|
||||
**Root Cause**: In `UIDrawable::get_click()`, the code was calling `->borrow()` on the `click_callable` unique_ptr without checking if it was null first.
|
||||
|
||||
**Fix**: Added null checks before accessing `click_callable->borrow()` for all UI element types.
|
||||
|
||||
**Result**: Click handler property access is now safe. Elements without click handlers return None as expected.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Enhanced Core Types
|
||||
|
||||
### Task #93: Vector Arithmetic
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Implement arithmetic operations for the Vector class
|
||||
|
||||
**Implementation**:
|
||||
1. Added PyNumberMethods structure with arithmetic operators:
|
||||
- Addition (`__add__`): v1 + v2
|
||||
- Subtraction (`__sub__`): v1 - v2
|
||||
- Multiplication (`__mul__`): v * scalar or scalar * v
|
||||
- Division (`__truediv__`): v / scalar
|
||||
- Negation (`__neg__`): -v
|
||||
- Absolute value (`__abs__`): abs(v) returns magnitude
|
||||
- Boolean check (`__bool__`): False for zero vector
|
||||
- Rich comparison (`__eq__`, `__ne__`)
|
||||
|
||||
2. Added vector-specific methods:
|
||||
- `magnitude()`: Returns length of vector
|
||||
- `magnitude_squared()`: Returns length squared (faster for comparisons)
|
||||
- `normalize()`: Returns unit vector in same direction
|
||||
- `dot(other)`: Dot product with another vector
|
||||
- `distance_to(other)`: Euclidean distance to another vector
|
||||
- `angle()`: Angle in radians from positive X axis
|
||||
- `copy()`: Create an independent copy
|
||||
|
||||
**Technical Details**:
|
||||
- PyNumberMethods structure defined in mcrfpydef namespace
|
||||
- Type checking returns NotImplemented for invalid operations
|
||||
- Zero division protection in divide operation
|
||||
- Zero vector normalization returns zero vector
|
||||
|
||||
**Test Results**:
|
||||
All arithmetic operations work correctly:
|
||||
- Basic arithmetic (add, subtract, multiply, divide, negate)
|
||||
- Comparison operations (equality, inequality)
|
||||
- Vector methods (magnitude, normalize, dot product, etc.)
|
||||
- Type safety with proper error handling
|
||||
|
||||
**Result**: Vector class now supports full arithmetic operations, making game math much more convenient and Pythonic.
|
||||
|
||||
---
|
||||
|
||||
### Bug Fix: UTF-8 Encoding for Python Output
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Issue**: Python print statements with unicode characters (like ✓ or emoji) were causing UnicodeEncodeError because stdout/stderr were using ASCII encoding.
|
||||
|
||||
**Root Cause**: Python's stdout and stderr were defaulting to ASCII encoding instead of UTF-8, even though `utf8_mode = 1` was set in PyPreConfig.
|
||||
|
||||
**Fix**: Properly configure UTF-8 encoding in PyConfig during initialization:
|
||||
```cpp
|
||||
PyConfig_SetString(&config, &config.stdio_encoding, L"UTF-8");
|
||||
PyConfig_SetString(&config, &config.stdio_errors, L"surrogateescape");
|
||||
config.configure_c_stdio = 1;
|
||||
```
|
||||
|
||||
**Implementation**:
|
||||
- Added UTF-8 configuration in `init_python()` for normal game mode
|
||||
- Added UTF-8 configuration in `init_python_with_config()` for interpreter mode
|
||||
- Used `surrogateescape` error handler for robustness with invalid UTF-8
|
||||
- Removed temporary stream wrapper hack in favor of proper configuration
|
||||
|
||||
**Technical Details**:
|
||||
- `stdio_encoding`: Sets encoding for stdin, stdout, stderr
|
||||
- `stdio_errors`: "surrogateescape" allows round-tripping invalid byte sequences
|
||||
- `configure_c_stdio`: Lets Python properly configure C runtime stdio behavior
|
||||
|
||||
**Result**: Unicode characters now work correctly in all Python output, including print statements, f-strings, and error messages. Tests can now use checkmarks (✓), cross marks (✗), emojis (🎮), and any other Unicode characters. The solution is cleaner and more robust than wrapping streams after initialization.
|
||||
|
||||
---
|
||||
|
||||
### Task #94: Color Helper Methods
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Add helper methods to the Color class for hex conversion and interpolation
|
||||
|
||||
**Implementation**:
|
||||
1. **from_hex(hex_string)** - Class method to create Color from hex string
|
||||
- Accepts formats: "#RRGGBB", "RRGGBB", "#RRGGBBAA", "RRGGBBAA"
|
||||
- Automatically strips "#" prefix if present
|
||||
- Validates hex string length and format
|
||||
- Returns new Color instance
|
||||
|
||||
2. **to_hex()** - Instance method to convert Color to hex string
|
||||
- Returns "#RRGGBB" for fully opaque colors
|
||||
- Returns "#RRGGBBAA" for colors with alpha < 255
|
||||
- Always includes "#" prefix
|
||||
|
||||
3. **lerp(other_color, t)** - Linear interpolation between colors
|
||||
- Interpolates all components (r, g, b, a)
|
||||
- Clamps t to [0.0, 1.0] range
|
||||
- t=0 returns self, t=1 returns other_color
|
||||
- Returns new Color instance
|
||||
|
||||
**Technical Details**:
|
||||
- Used `std::stoul` for hex parsing with base 16
|
||||
- `snprintf` for efficient hex string formatting
|
||||
- Linear interpolation: `result = start + (end - start) * t`
|
||||
- Added as methods to PyColorType with METH_CLASS flag for from_hex
|
||||
|
||||
**Test Results**:
|
||||
- All hex formats parse correctly
|
||||
- Round-trip conversion preserves values
|
||||
- Interpolation produces smooth gradients
|
||||
- Error handling works for invalid input
|
||||
|
||||
**Result**: Color class now has convenient helper methods for common color operations. This makes it easier to work with colors in games, especially for UI theming and effects.
|
||||
|
||||
### Task: #103 - Timer objects
|
||||
|
||||
**Issue**: Add mcrfpy.Timer object to encapsulate timer functionality with pause/resume/cancel capabilities
|
||||
|
||||
**Research**:
|
||||
- Current timer system uses setTimer/delTimer with string names
|
||||
- Timers stored in GameEngine::timers map as shared_ptr<PyTimerCallable>
|
||||
- No pause/resume functionality exists
|
||||
- Need object-oriented interface for better control
|
||||
|
||||
**Implementation**:
|
||||
1. Created PyTimer.h/cpp with PyTimerObject structure
|
||||
2. Enhanced PyTimerCallable with pause/resume state tracking:
|
||||
- Added paused, pause_start_time, total_paused_time members
|
||||
- Modified hasElapsed() to check paused state
|
||||
- Adjusted timing calculations to account for paused duration
|
||||
3. Timer object features:
|
||||
- Constructor: Timer(name, callback, interval)
|
||||
- Methods: pause(), resume(), cancel(), restart()
|
||||
- Properties: interval, remaining, paused, active, callback
|
||||
- Automatically registers with game engine on creation
|
||||
4. Pause/resume logic:
|
||||
- When paused: Store pause time, set paused flag
|
||||
- When resumed: Calculate pause duration, adjust last_ran time
|
||||
- Prevents timer from "catching up" after resume
|
||||
|
||||
**Key Decisions**:
|
||||
- Timer object owns a shared_ptr to PyTimerCallable for lifetime management
|
||||
- Made GameEngine::runtime and timers public for Timer access
|
||||
- Used placement new for std::string member in PyTimerObject
|
||||
- Fixed const-correctness issue with isNone() method
|
||||
|
||||
**Test Results**:
|
||||
- Timer creation and basic firing works correctly
|
||||
- Pause/resume maintains proper timing without rapid catch-up
|
||||
- Cancel removes timer from system properly
|
||||
- Restart resets timer to current time
|
||||
- Interval modification takes effect immediately
|
||||
- Timer states (active, paused) report correctly
|
||||
|
||||
**Result**: Timer objects provide a cleaner, more intuitive API for managing timed callbacks. Games can now pause/resume timers for menus, animations, or gameplay mechanics. The object-oriented interface is more Pythonic than the string-based setTimer/delTimer approach.
|
||||
|
||||
---
|
||||
|
||||
### Test Suite Stabilization
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Goal**: Make all test files terminate properly and fix various test failures
|
||||
|
||||
**Issues Addressed**:
|
||||
|
||||
1. **Audio Cleanup Warning**
|
||||
- Issue: `AL lib: (EE) alc_cleanup: 1 device not closed` warning on exit
|
||||
- Attempted Fix: Converted static audio objects (sf::Music, sf::Sound) to pointers and added explicit cleanup in api_shutdown()
|
||||
- Result: Warning persists but is a known OpenAL/SFML issue that doesn't affect functionality
|
||||
- This is a benign warning seen in many SFML applications
|
||||
|
||||
2. **Test Termination Issues**
|
||||
- Issue: test_click_init.py and test_frame_children.py didn't terminate on their own
|
||||
- Fix: Added `mcrfpy.delTimer("test")` at start of test functions to prevent re-running
|
||||
- Added fallback exit timers with 1-2 second timeouts as safety net
|
||||
- Result: All tests now terminate properly
|
||||
|
||||
3. **Missing Python Methods/Properties**
|
||||
- Issue: visible, opacity, get_bounds, move, resize methods were missing from UI objects
|
||||
- Implementation:
|
||||
- Created UIDrawable_methods.h with template functions for shared functionality
|
||||
- Added UIDRAWABLE_METHODS and UIDRAWABLE_GETSETTERS macros
|
||||
- Updated all UI classes (Frame, Caption, Sprite, Grid) to include these
|
||||
- Special handling for UIEntity which wraps UISprite - created template specializations
|
||||
- Technical Details:
|
||||
- Template functions allow code reuse across different PyObject types
|
||||
- UIEntity delegates to its sprite member for drawable properties
|
||||
- Fixed static/extern linkage issues with method arrays
|
||||
- Result: All UI objects now have complete drawable interface
|
||||
|
||||
4. **test_sprite_texture_swap.py Fixes**
|
||||
- TypeError Issue: Click handler was missing 4th parameter 'action'
|
||||
- Fix: Updated click handler signature from (x, y, button) to (x, y, button, action)
|
||||
- Texture Comparison Issue: Direct object comparison failed because sprite.texture returns new wrapper
|
||||
- Fix: Changed tests to avoid direct texture object comparison, use state tracking instead
|
||||
- Result: Test passes with all functionality verified
|
||||
|
||||
5. **Timer Test Segfaults**
|
||||
- Issue: test_timer_object.py and test_timer_object_fixed.py mentioned potential segfaults
|
||||
- Investigation: Tests were actually running fine, no segfaults detected
|
||||
- Both timer tests complete successfully with proper exit codes
|
||||
|
||||
6. **test_drawable_base.py Segfault**
|
||||
- Issue: Segmentation fault when rendering Caption objects in headless mode
|
||||
- Root Cause: Graphics driver crash in iris_dri.so when rendering text without display
|
||||
- Stack trace showed crash in sf::Text::draw -> Font::getGlyph -> Texture::update
|
||||
- Fix: Skip visual test portion in headless mode to avoid rendering
|
||||
- Result: Test completes successfully, all non-visual tests pass
|
||||
|
||||
**Additional Issues Resolved**:
|
||||
|
||||
1. **Caption Constructor Format**
|
||||
- Issue: test_drawable_base.py was using incorrect Caption constructor format
|
||||
- Fix: Changed from keyword arguments to positional format: `Caption((x, y), text)`
|
||||
- Caption doesn't support x=, y= keywords yet, only positional or pos= formats
|
||||
|
||||
2. **Debug Print Cleanup**
|
||||
- Removed debug print statement in UICaption color setter that was outputting "got 255, 255, 255, 255"
|
||||
- This was cluttering test output
|
||||
|
||||
**Test Suite Status**:
|
||||
- ✓ test_click_init.py - Terminates properly
|
||||
- ✓ test_frame_children.py - Terminates properly
|
||||
- ✓ test_sprite_texture_swap.py - All tests pass, terminates properly
|
||||
- ✓ test_timer_object.py - All tests pass, terminates properly
|
||||
- ✓ test_timer_object_fixed.py - All tests pass, terminates properly
|
||||
- ✓ test_drawable_base.py - All tests pass (visual test skipped in headless)
|
||||
|
||||
**Result**: All test files are now "airtight" - they complete successfully, terminate on their own, and handle edge cases properly. The only remaining output is the benign OpenAL cleanup warning.
|
||||
|
||||
---
|
||||
|
||||
### Window Close Segfault Fix
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
**Issue**: Segmentation fault when closing the window via the OS X button (but not when exiting via Ctrl+C)
|
||||
|
||||
**Root Cause**:
|
||||
When the window was closed externally via the X button, the cleanup order was incorrect:
|
||||
1. SFML window would be destroyed by the window manager
|
||||
2. GameEngine destructor would delete scenes containing Python objects
|
||||
3. Python was still running and might try to access destroyed C++ objects
|
||||
4. This caused a segfault due to accessing freed memory
|
||||
|
||||
**Solution**:
|
||||
1. Added `cleanup()` method to GameEngine class that properly clears Python references before C++ destruction
|
||||
2. The cleanup method:
|
||||
- Clears all timers (which hold Python callables)
|
||||
- Clears McRFPy_API's reference to the game engine
|
||||
- Explicitly closes the window if still open
|
||||
3. Call `cleanup()` at the end of the run loop when window close is detected
|
||||
4. Also call in destructor with guard to prevent double cleanup
|
||||
5. Added `cleaned_up` member variable to track cleanup state
|
||||
|
||||
**Implementation Details**:
|
||||
- Modified `GameEngine::run()` to call `cleanup()` before exiting
|
||||
- Modified `GameEngine::~GameEngine()` to call `cleanup()` before deleting scenes
|
||||
- Added `GameEngine::cleanup()` method with proper cleanup sequence
|
||||
- Added `bool cleaned_up` member to prevent double cleanup
|
||||
|
||||
**Result**: Window can now be closed via the X button without segfaulting. Python references are properly cleared before C++ objects are destroyed.
|
||||
|
||||
---
|
||||
|
||||
### Additional Improvements
|
||||
|
||||
**Status**: Completed
|
||||
**Date**: 2025-07-06
|
||||
|
||||
1. **Caption Keyword Arguments**
|
||||
- Issue: Caption didn't accept `x, y` as keyword arguments (e.g., `Caption("text", x=5, y=10)`)
|
||||
- Solution: Rewrote Caption init to handle multiple argument patterns:
|
||||
- `Caption("text", x=10, y=20)` - text first with keyword position
|
||||
- `Caption(x, y, "text")` - traditional positional arguments
|
||||
- `Caption((x, y), "text")` - position tuple format
|
||||
- All patterns now work correctly with full keyword support
|
||||
|
||||
2. **Code Organization Refactoring**
|
||||
- Issue: `UIDrawable_methods.h` was a separate file that could have been better integrated
|
||||
- Solution:
|
||||
- Moved template functions and macros from `UIDrawable_methods.h` into `UIBase.h`
|
||||
- Created `UIEntityPyMethods.h` for UIEntity-specific implementations
|
||||
- Removed the now-unnecessary `UIDrawable_methods.h`
|
||||
- Result: Better code organization with Python binding code in appropriate headers
|
||||
|
|
@ -0,0 +1,200 @@
|
|||
# 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.
|
||||
Loading…
Reference in New Issue