2024-04-20 10:32:04 -04:00
# include "UIGrid.h"
# include "GameEngine.h"
# include "McRFPy_API.h"
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
# include "PyArgHelpers.h"
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
# include <algorithm>
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// UIDrawable methods now in UIBase.h
2024-04-20 10:32:04 -04:00
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
UIGrid : : UIGrid ( )
: grid_x ( 0 ) , grid_y ( 0 ) , zoom ( 1.0f ) , center_x ( 0.0f ) , center_y ( 0.0f ) , ptex ( nullptr ) ,
fill_color ( 8 , 8 , 8 , 255 ) , tcod_map ( nullptr ) , tcod_dijkstra ( nullptr ) , tcod_path ( nullptr ) ,
perspective ( - 1 ) // Default to omniscient view
{
// Initialize entities list
entities = std : : make_shared < std : : list < std : : shared_ptr < UIEntity > > > ( ) ;
// Initialize box with safe defaults
box . setSize ( sf : : Vector2f ( 0 , 0 ) ) ;
position = sf : : Vector2f ( 0 , 0 ) ; // Set base class position
box . setPosition ( position ) ; // Sync box position
box . setFillColor ( sf : : Color ( 0 , 0 , 0 , 0 ) ) ;
// Initialize render texture (small default size)
renderTexture . create ( 1 , 1 ) ;
// Initialize output sprite
output . setTextureRect ( sf : : IntRect ( 0 , 0 , 0 , 0 ) ) ;
output . setPosition ( 0 , 0 ) ;
output . setTexture ( renderTexture . getTexture ( ) ) ;
// Points vector starts empty (grid_x * grid_y = 0)
// TCOD map will be created when grid is resized
}
2024-04-20 10:32:04 -04:00
UIGrid : : UIGrid ( int gx , int gy , std : : shared_ptr < PyTexture > _ptex , sf : : Vector2f _xy , sf : : Vector2f _wh )
: grid_x ( gx ) , grid_y ( gy ) ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
zoom ( 1.0f ) ,
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
ptex ( _ptex ) , points ( gx * gy ) ,
fill_color ( 8 , 8 , 8 , 255 ) , tcod_map ( nullptr ) , tcod_dijkstra ( nullptr ) , tcod_path ( nullptr ) ,
perspective ( - 1 ) // Default to omniscient view
2024-04-20 10:32:04 -04:00
{
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Use texture dimensions if available, otherwise use defaults
int cell_width = _ptex ? _ptex - > sprite_width : DEFAULT_CELL_WIDTH ;
int cell_height = _ptex ? _ptex - > sprite_height : DEFAULT_CELL_HEIGHT ;
center_x = ( gx / 2 ) * cell_width ;
center_y = ( gy / 2 ) * cell_height ;
2024-04-20 10:32:04 -04:00
entities = std : : make_shared < std : : list < std : : shared_ptr < UIEntity > > > ( ) ;
box . setSize ( _wh ) ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
position = _xy ; // Set base class position
box . setPosition ( position ) ; // Sync box position
2024-04-20 10:32:04 -04:00
box . setFillColor ( sf : : Color ( 0 , 0 , 0 , 0 ) ) ;
// create renderTexture with maximum theoretical size; sprite can resize to show whatever amount needs to be rendered
renderTexture . create ( 1920 , 1080 ) ; // TODO - renderTexture should be window size; above 1080p this will cause rendering errors
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Only initialize sprite if texture is available
if ( ptex ) {
sprite = ptex - > sprite ( 0 ) ;
}
2024-04-20 10:32:04 -04:00
output . setTextureRect (
sf : : IntRect ( 0 , 0 ,
box . getSize ( ) . x , box . getSize ( ) . y ) ) ;
output . setPosition ( box . getPosition ( ) ) ;
// textures are upside-down inside renderTexture
output . setTexture ( renderTexture . getTexture ( ) ) ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Create TCOD map
tcod_map = new TCODMap ( gx , gy ) ;
// Create TCOD dijkstra pathfinder
tcod_dijkstra = new TCODDijkstra ( tcod_map ) ;
// Create TCOD A* pathfinder
tcod_path = new TCODPath ( tcod_map ) ;
// Initialize grid points with parent reference
for ( int y = 0 ; y < gy ; y + + ) {
for ( int x = 0 ; x < gx ; x + + ) {
int idx = y * gx + x ;
points [ idx ] . grid_x = x ;
points [ idx ] . grid_y = y ;
points [ idx ] . parent_grid = this ;
}
}
// Initial sync of TCOD map
syncTCODMap ( ) ;
2024-04-20 10:32:04 -04:00
}
void UIGrid : : update ( ) { }
2025-03-05 20:21:24 -05:00
void UIGrid : : render ( sf : : Vector2f offset , sf : : RenderTarget & target )
2024-04-20 10:32:04 -04:00
{
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Check visibility
if ( ! visible ) return ;
// TODO: Apply opacity to output sprite
2025-03-05 20:21:24 -05:00
output . setPosition ( box . getPosition ( ) + offset ) ; // output sprite can move; update position when drawing
2024-04-20 10:32:04 -04:00
// output size can change; update size when drawing
output . setTextureRect (
sf : : IntRect ( 0 , 0 ,
box . getSize ( ) . x , box . getSize ( ) . y ) ) ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
renderTexture . clear ( fill_color ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Get cell dimensions - use texture if available, otherwise defaults
int cell_width = ptex ? ptex - > sprite_width : DEFAULT_CELL_WIDTH ;
int cell_height = ptex ? ptex - > sprite_height : DEFAULT_CELL_HEIGHT ;
2024-04-20 10:32:04 -04:00
// sprites that are visible according to zoom, center_x, center_y, and box width
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
float center_x_sq = center_x / cell_width ;
float center_y_sq = center_y / cell_height ;
2024-04-20 10:32:04 -04:00
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
float width_sq = box . getSize ( ) . x / ( cell_width * zoom ) ;
float height_sq = box . getSize ( ) . y / ( cell_height * zoom ) ;
2024-04-20 10:32:04 -04:00
float left_edge = center_x_sq - ( width_sq / 2.0 ) ;
float top_edge = center_y_sq - ( height_sq / 2.0 ) ;
int left_spritepixels = center_x - ( box . getSize ( ) . x / 2.0 / zoom ) ;
int top_spritepixels = center_y - ( box . getSize ( ) . y / 2.0 / zoom ) ;
//sprite.setScale(sf::Vector2f(zoom, zoom));
sf : : RectangleShape r ; // for colors and overlays
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
r . setSize ( sf : : Vector2f ( cell_width * zoom , cell_height * zoom ) ) ;
2024-04-20 10:32:04 -04:00
r . setOutlineThickness ( 0 ) ;
int x_limit = left_edge + width_sq + 2 ;
if ( x_limit > grid_x ) x_limit = grid_x ;
int y_limit = top_edge + height_sq + 2 ;
if ( y_limit > grid_y ) y_limit = grid_y ;
// base layer - bottom color, tile sprite ("ground")
for ( int x = ( left_edge - 1 > = 0 ? left_edge - 1 : 0 ) ;
x < x_limit ; //x < view_width;
x + = 1 )
{
//for (float y = (top_edge >= 0 ? top_edge : 0);
for ( int y = ( top_edge - 1 > = 0 ? top_edge - 1 : 0 ) ;
y < y_limit ; //y < view_height;
y + = 1 )
{
auto pixel_pos = sf : : Vector2f (
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
( x * cell_width - left_spritepixels ) * zoom ,
( y * cell_height - top_spritepixels ) * zoom ) ;
2024-04-20 10:32:04 -04:00
auto gridpoint = at ( std : : floor ( x ) , std : : floor ( y ) ) ;
//sprite.setPosition(pixel_pos);
r . setPosition ( pixel_pos ) ;
r . setFillColor ( gridpoint . color ) ;
renderTexture . draw ( r ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// tilesprite - only draw if texture is available
2024-04-20 10:32:04 -04:00
// if discovered but not visible, set opacity to 90%
// if not discovered... just don't draw it?
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
if ( ptex & & gridpoint . tilesprite ! = - 1 ) {
2024-04-20 10:32:04 -04:00
sprite = ptex - > sprite ( gridpoint . tilesprite , pixel_pos , sf : : Vector2f ( zoom , zoom ) ) ; //setSprite(gridpoint.tilesprite);;
renderTexture . draw ( sprite ) ;
}
}
}
// middle layer - entities
// disabling entity rendering until I can render their UISprite inside the rendertexture (not directly to window)
for ( auto e : * entities ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Skip out-of-bounds entities for performance
// Check if entity is within visible bounds (with 1 cell margin for partially visible entities)
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 as it's not visible
}
2024-04-20 10:32:04 -04:00
//auto drawent = e->cGrid->indexsprite.drawable();
auto & drawent = e - > sprite ;
//drawent.setScale(zoom, zoom);
drawent . setScale ( sf : : Vector2f ( zoom , zoom ) ) ;
auto pixel_pos = sf : : Vector2f (
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
( e - > position . x * cell_width - left_spritepixels ) * zoom ,
( e - > position . y * cell_height - top_spritepixels ) * zoom ) ;
2024-04-20 10:32:04 -04:00
//drawent.setPosition(pixel_pos);
//renderTexture.draw(drawent);
drawent . render ( pixel_pos , renderTexture ) ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// top layer - opacity for discovered / visible status based on perspective
// Only render visibility overlay if perspective is set (not omniscient)
if ( perspective > = 0 & & perspective < static_cast < int > ( entities - > size ( ) ) ) {
// Get the entity whose perspective we're using
auto it = entities - > begin ( ) ;
std : : advance ( it , perspective ) ;
auto & entity = * it ;
// Create rectangle for overlays
sf : : RectangleShape overlay ;
overlay . setSize ( sf : : Vector2f ( cell_width * zoom , cell_height * zoom ) ) ;
for ( int x = ( left_edge - 1 > = 0 ? left_edge - 1 : 0 ) ;
x < x_limit ;
x + = 1 )
2024-04-20 10:32:04 -04:00
{
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
for ( int y = ( top_edge - 1 > = 0 ? top_edge - 1 : 0 ) ;
y < y_limit ;
y + = 1 )
{
// Skip out-of-bounds cells
if ( x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) continue ;
auto pixel_pos = sf : : Vector2f (
( x * cell_width - left_spritepixels ) * zoom ,
( y * cell_height - top_spritepixels ) * zoom ) ;
// Get visibility state from entity's perspective
int idx = y * grid_x + x ;
if ( idx > = 0 & & idx < static_cast < int > ( entity - > gridstate . size ( ) ) ) {
const auto & state = entity - > gridstate [ idx ] ;
overlay . setPosition ( pixel_pos ) ;
// Three overlay colors as specified:
if ( ! state . discovered ) {
// Never seen - black
overlay . setFillColor ( sf : : Color ( 0 , 0 , 0 , 255 ) ) ;
renderTexture . draw ( overlay ) ;
} else if ( ! state . visible ) {
// Discovered but not currently visible - dark gray
overlay . setFillColor ( sf : : Color ( 32 , 32 , 40 , 192 ) ) ;
renderTexture . draw ( overlay ) ;
}
// If visible and discovered, no overlay (fully visible)
}
2024-04-20 10:32:04 -04:00
}
}
}
// grid lines for testing & validation
/*
sf : : Vertex line [ ] =
{
sf : : Vertex ( sf : : Vector2f ( 0 , 0 ) , sf : : Color : : Red ) ,
sf : : Vertex ( box . getSize ( ) , sf : : Color : : Red ) ,
} ;
renderTexture . draw ( line , 2 , sf : : Lines ) ;
sf : : Vertex lineb [ ] =
{
sf : : Vertex ( sf : : Vector2f ( 0 , box . getSize ( ) . y ) , sf : : Color : : Blue ) ,
sf : : Vertex ( sf : : Vector2f ( box . getSize ( ) . x , 0 ) , sf : : Color : : Blue ) ,
} ;
renderTexture . draw ( lineb , 2 , sf : : Lines ) ;
*/
// render to window
renderTexture . display ( ) ;
2025-03-05 20:21:24 -05:00
//Resources::game->getWindow().draw(output);
target . draw ( output ) ;
2024-04-20 10:32:04 -04:00
}
UIGridPoint & UIGrid : : at ( int x , int y )
{
return points [ y * grid_x + x ] ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
UIGrid : : ~ UIGrid ( )
{
if ( tcod_path ) {
delete tcod_path ;
tcod_path = nullptr ;
}
if ( tcod_dijkstra ) {
delete tcod_dijkstra ;
tcod_dijkstra = nullptr ;
}
if ( tcod_map ) {
delete tcod_map ;
tcod_map = nullptr ;
}
}
2024-04-20 10:32:04 -04:00
PyObjectsEnum UIGrid : : derived_type ( )
{
return PyObjectsEnum : : UIGRID ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// TCOD integration methods
void UIGrid : : syncTCODMap ( )
{
if ( ! tcod_map ) return ;
for ( int y = 0 ; y < grid_y ; y + + ) {
for ( int x = 0 ; x < grid_x ; x + + ) {
const UIGridPoint & point = at ( x , y ) ;
tcod_map - > setProperties ( x , y , point . transparent , point . walkable ) ;
}
}
}
void UIGrid : : syncTCODMapCell ( int x , int y )
{
if ( ! tcod_map | | x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) return ;
const UIGridPoint & point = at ( x , y ) ;
tcod_map - > setProperties ( x , y , point . transparent , point . walkable ) ;
}
void UIGrid : : computeFOV ( int x , int y , int radius , bool light_walls , TCOD_fov_algorithm_t algo )
{
if ( ! tcod_map | | x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) return ;
tcod_map - > computeFov ( x , y , radius , light_walls , algo ) ;
}
bool UIGrid : : isInFOV ( int x , int y ) const
{
if ( ! tcod_map | | x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) return false ;
return tcod_map - > isInFov ( x , y ) ;
}
std : : vector < std : : pair < int , int > > UIGrid : : findPath ( int x1 , int y1 , int x2 , int y2 , float diagonalCost )
{
std : : vector < std : : pair < int , int > > path ;
if ( ! tcod_map | | x1 < 0 | | x1 > = grid_x | | y1 < 0 | | y1 > = grid_y | |
x2 < 0 | | x2 > = grid_x | | y2 < 0 | | y2 > = grid_y ) {
return path ;
}
TCODPath tcod_path ( tcod_map , diagonalCost ) ;
if ( tcod_path . compute ( x1 , y1 , x2 , y2 ) ) {
for ( int i = 0 ; i < tcod_path . size ( ) ; i + + ) {
int x , y ;
tcod_path . get ( i , & x , & y ) ;
path . push_back ( std : : make_pair ( x , y ) ) ;
}
}
return path ;
}
void UIGrid : : computeDijkstra ( int rootX , int rootY , float diagonalCost )
{
if ( ! tcod_map | | ! tcod_dijkstra | | rootX < 0 | | rootX > = grid_x | | rootY < 0 | | rootY > = grid_y ) return ;
// Compute the Dijkstra map from the root position
tcod_dijkstra - > compute ( rootX , rootY ) ;
}
float UIGrid : : getDijkstraDistance ( int x , int y ) const
{
if ( ! tcod_dijkstra | | x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) {
return - 1.0f ; // Invalid position
}
return tcod_dijkstra - > getDistance ( x , y ) ;
}
std : : vector < std : : pair < int , int > > UIGrid : : getDijkstraPath ( int x , int y ) const
{
std : : vector < std : : pair < int , int > > path ;
if ( ! tcod_dijkstra | | x < 0 | | x > = grid_x | | y < 0 | | y > = grid_y ) {
return path ; // Empty path for invalid position
}
// Set the destination
if ( tcod_dijkstra - > setPath ( x , y ) ) {
// Walk the path and collect points
int px , py ;
while ( tcod_dijkstra - > walk ( & px , & py ) ) {
path . push_back ( std : : make_pair ( px , py ) ) ;
}
}
return path ;
}
// A* pathfinding implementation
std : : vector < std : : pair < int , int > > UIGrid : : computeAStarPath ( int x1 , int y1 , int x2 , int y2 , float diagonalCost )
{
std : : vector < std : : pair < int , int > > path ;
// Validate inputs
if ( ! tcod_map | | ! tcod_path | |
x1 < 0 | | x1 > = grid_x | | y1 < 0 | | y1 > = grid_y | |
x2 < 0 | | x2 > = grid_x | | y2 < 0 | | y2 > = grid_y ) {
return path ; // Return empty path
}
// Set diagonal cost (TCODPath doesn't take it as parameter to compute)
// Instead, diagonal cost is set during TCODPath construction
// For now, we'll use the default diagonal cost from the constructor
// Compute the path
bool success = tcod_path - > compute ( x1 , y1 , x2 , y2 ) ;
if ( success ) {
// Get the computed path
int pathSize = tcod_path - > size ( ) ;
path . reserve ( pathSize ) ;
// TCOD path includes the starting position, so we start from index 0
for ( int i = 0 ; i < pathSize ; i + + ) {
int px , py ;
tcod_path - > get ( i , & px , & py ) ;
path . push_back ( std : : make_pair ( px , py ) ) ;
}
}
return path ;
}
// Phase 1 implementations
sf : : FloatRect UIGrid : : get_bounds ( ) const
{
auto size = box . getSize ( ) ;
return sf : : FloatRect ( position . x , position . y , size . x , size . y ) ;
}
void UIGrid : : move ( float dx , float dy )
{
position . x + = dx ;
position . y + = dy ;
box . setPosition ( position ) ; // Keep box in sync
output . setPosition ( position ) ; // Keep output sprite in sync too
}
void UIGrid : : resize ( float w , float h )
{
box . setSize ( sf : : Vector2f ( w , h ) ) ;
// Recreate render texture with new size
if ( w > 0 & & h > 0 ) {
renderTexture . create ( static_cast < unsigned int > ( w ) , static_cast < unsigned int > ( h ) ) ;
output . setTexture ( renderTexture . getTexture ( ) ) ;
}
}
void UIGrid : : onPositionChanged ( )
{
// Sync box and output sprite positions with base class position
box . setPosition ( position ) ;
output . setPosition ( position ) ;
}
2024-04-20 10:32:04 -04:00
std : : shared_ptr < PyTexture > UIGrid : : getTexture ( )
{
return ptex ;
}
UIDrawable * UIGrid : : click_at ( sf : : Vector2f point )
{
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Check grid bounds first
if ( ! box . getGlobalBounds ( ) . contains ( point ) ) {
return nullptr ;
2024-04-20 10:32:04 -04:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Transform to local coordinates
sf : : Vector2f localPoint = point - box . getPosition ( ) ;
// Get cell dimensions
int cell_width = ptex ? ptex - > sprite_width : DEFAULT_CELL_WIDTH ;
int cell_height = ptex ? ptex - > sprite_height : DEFAULT_CELL_HEIGHT ;
// Calculate visible area parameters (from render function)
float center_x_sq = center_x / cell_width ;
float center_y_sq = center_y / cell_height ;
float width_sq = box . getSize ( ) . x / ( cell_width * zoom ) ;
float height_sq = box . getSize ( ) . y / ( cell_height * zoom ) ;
int left_spritepixels = center_x - ( box . getSize ( ) . x / 2.0 / zoom ) ;
int top_spritepixels = center_y - ( box . getSize ( ) . y / 2.0 / zoom ) ;
// Convert click position to grid coordinates
float grid_x = ( localPoint . x / zoom + left_spritepixels ) / cell_width ;
float grid_y = ( localPoint . y / zoom + top_spritepixels ) / cell_height ;
// Check entities in reverse order (assuming they should be checked top to bottom)
// Note: entities list is not sorted by z-index currently, but we iterate in reverse
// to match the render order assumption
if ( entities ) {
for ( auto it = entities - > rbegin ( ) ; it ! = entities - > rend ( ) ; + + it ) {
auto & entity = * it ;
if ( ! entity | | ! entity - > sprite . visible ) continue ;
// Check if click is within entity's grid cell
// Entities occupy a 1x1 grid cell centered on their position
float dx = grid_x - entity - > position . x ;
float dy = grid_y - entity - > position . y ;
if ( dx > = - 0.5f & & dx < 0.5f & & dy > = - 0.5f & & dy < 0.5f ) {
// Click is within the entity's cell
// Check if entity sprite has a click handler
// For now, we return the entity's sprite as the click target
// Note: UIEntity doesn't derive from UIDrawable, so we check its sprite
if ( entity - > sprite . click_callable ) {
return & entity - > sprite ;
}
}
}
}
// No entity handled it, check if grid itself has handler
if ( click_callable ) {
return this ;
}
return nullptr ;
2024-04-20 10:32:04 -04:00
}
int UIGrid : : init ( PyUIGridObject * self , PyObject * args , PyObject * kwds ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Default values
int grid_x = 0 , grid_y = 0 ;
float x = 0.0f , y = 0.0f , w = 0.0f , h = 0.0f ;
PyObject * textureObj = nullptr ;
// Check if first argument is a tuple (for tuple-based initialization)
bool has_tuple_first_arg = false ;
if ( args & & PyTuple_Size ( args ) > 0 ) {
PyObject * first_arg = PyTuple_GetItem ( args , 0 ) ;
if ( PyTuple_Check ( first_arg ) ) {
has_tuple_first_arg = true ;
}
2024-04-20 10:32:04 -04:00
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Try tuple-based parsing if we have a tuple as first argument
if ( has_tuple_first_arg ) {
int arg_idx = 0 ;
auto grid_size_result = PyArgHelpers : : parseGridSize ( args , kwds , & arg_idx ) ;
// If grid size parsing failed with an error, report it
if ( ! grid_size_result . valid ) {
if ( grid_size_result . error ) {
PyErr_SetString ( PyExc_TypeError , grid_size_result . error ) ;
} else {
PyErr_SetString ( PyExc_TypeError , " Invalid grid size tuple " ) ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return - 1 ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// We got a valid grid size
grid_x = grid_size_result . grid_w ;
grid_y = grid_size_result . grid_h ;
// Try to parse position and size
auto pos_result = PyArgHelpers : : parsePosition ( args , kwds , & arg_idx ) ;
if ( pos_result . valid ) {
x = pos_result . x ;
y = pos_result . y ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
auto size_result = PyArgHelpers : : parseSize ( args , kwds , & arg_idx ) ;
if ( size_result . valid ) {
w = size_result . w ;
h = size_result . h ;
} else {
// Default size based on grid dimensions
w = grid_x * 16.0f ;
h = grid_y * 16.0f ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Parse remaining arguments (texture)
static const char * remaining_keywords [ ] = { " texture " , nullptr } ;
Py_ssize_t total_args = PyTuple_Size ( args ) ;
PyObject * remaining_args = PyTuple_GetSlice ( args , arg_idx , total_args ) ;
PyArg_ParseTupleAndKeywords ( remaining_args , kwds , " |O " ,
const_cast < char * * > ( remaining_keywords ) ,
& textureObj ) ;
Py_DECREF ( remaining_args ) ;
2025-03-05 20:21:24 -05:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Traditional format parsing
else {
static const char * keywords [ ] = {
" grid_x " , " grid_y " , " texture " , " pos " , " size " , " grid_size " , nullptr
} ;
PyObject * pos_obj = nullptr ;
PyObject * size_obj = nullptr ;
PyObject * grid_size_obj = nullptr ;
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " |iiOOOO " ,
const_cast < char * * > ( keywords ) ,
& grid_x , & grid_y , & textureObj ,
& pos_obj , & size_obj , & grid_size_obj ) ) {
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return - 1 ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Handle grid_size override
if ( grid_size_obj & & grid_size_obj ! = Py_None ) {
if ( PyTuple_Check ( grid_size_obj ) & & PyTuple_Size ( grid_size_obj ) = = 2 ) {
PyObject * x_obj = PyTuple_GetItem ( grid_size_obj , 0 ) ;
PyObject * y_obj = PyTuple_GetItem ( grid_size_obj , 1 ) ;
if ( PyLong_Check ( x_obj ) & & PyLong_Check ( y_obj ) ) {
grid_x = PyLong_AsLong ( x_obj ) ;
grid_y = PyLong_AsLong ( y_obj ) ;
} else {
PyErr_SetString ( PyExc_TypeError , " grid_size must contain integers " ) ;
return - 1 ;
}
} else {
PyErr_SetString ( PyExc_TypeError , " grid_size must be a tuple of two integers " ) ;
return - 1 ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
}
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Handle position
if ( pos_obj & & pos_obj ! = Py_None ) {
if ( PyTuple_Check ( pos_obj ) & & PyTuple_Size ( pos_obj ) = = 2 ) {
PyObject * x_val = PyTuple_GetItem ( pos_obj , 0 ) ;
PyObject * y_val = PyTuple_GetItem ( pos_obj , 1 ) ;
if ( ( PyFloat_Check ( x_val ) | | PyLong_Check ( x_val ) ) & &
( PyFloat_Check ( y_val ) | | PyLong_Check ( y_val ) ) ) {
x = PyFloat_Check ( x_val ) ? PyFloat_AsDouble ( x_val ) : PyLong_AsLong ( x_val ) ;
y = PyFloat_Check ( y_val ) ? PyFloat_AsDouble ( y_val ) : PyLong_AsLong ( y_val ) ;
} else {
PyErr_SetString ( PyExc_TypeError , " pos must contain numbers " ) ;
return - 1 ;
}
} else {
PyErr_SetString ( PyExc_TypeError , " pos must be a tuple of two numbers " ) ;
return - 1 ;
}
}
// Handle size
if ( size_obj & & size_obj ! = Py_None ) {
if ( PyTuple_Check ( size_obj ) & & PyTuple_Size ( size_obj ) = = 2 ) {
PyObject * w_val = PyTuple_GetItem ( size_obj , 0 ) ;
PyObject * h_val = PyTuple_GetItem ( size_obj , 1 ) ;
if ( ( PyFloat_Check ( w_val ) | | PyLong_Check ( w_val ) ) & &
( PyFloat_Check ( h_val ) | | PyLong_Check ( h_val ) ) ) {
w = PyFloat_Check ( w_val ) ? PyFloat_AsDouble ( w_val ) : PyLong_AsLong ( w_val ) ;
h = PyFloat_Check ( h_val ) ? PyFloat_AsDouble ( h_val ) : PyLong_AsLong ( h_val ) ;
} else {
PyErr_SetString ( PyExc_TypeError , " size must contain numbers " ) ;
return - 1 ;
}
} else {
PyErr_SetString ( PyExc_TypeError , " size must be a tuple of two numbers " ) ;
return - 1 ;
}
} else {
// Default size based on grid
w = grid_x * 16.0f ;
h = grid_y * 16.0f ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
}
2025-03-05 20:21:24 -05:00
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Validate grid dimensions
if ( grid_x < = 0 | | grid_y < = 0 ) {
PyErr_SetString ( PyExc_ValueError , " Grid dimensions must be positive integers " ) ;
return - 1 ;
}
// At this point we have x, y, w, h values from either parsing method
// Convert PyObject texture to shared_ptr<PyTexture>
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
std : : shared_ptr < PyTexture > texture_ptr = nullptr ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Allow None or NULL for texture - use default texture in that case
if ( textureObj & & textureObj ! = Py_None ) {
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
if ( ! PyObject_IsInstance ( textureObj , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Texture " ) ) ) {
PyErr_SetString ( PyExc_TypeError , " texture must be a mcrfpy.Texture instance or None " ) ;
return - 1 ;
}
PyTextureObject * pyTexture = reinterpret_cast < PyTextureObject * > ( textureObj ) ;
texture_ptr = pyTexture - > data ;
} else {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Use default texture when None is provided or texture not specified
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
texture_ptr = McRFPy_API : : default_texture ;
2024-04-20 10:32:04 -04:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Adjust size based on texture if available and size not explicitly set
if ( texture_ptr & & w = = grid_x * 16.0f & & h = = grid_y * 16.0f ) {
w = grid_x * texture_ptr - > sprite_width ;
h = grid_y * texture_ptr - > sprite_height ;
}
self - > data = std : : make_shared < UIGrid > ( grid_x , grid_y , texture_ptr ,
sf : : Vector2f ( x , y ) , sf : : Vector2f ( w , h ) ) ;
2024-04-20 10:32:04 -04:00
return 0 ; // Success
}
PyObject * UIGrid : : get_grid_size ( PyUIGridObject * self , void * closure ) {
return Py_BuildValue ( " (ii) " , self->data->grid_x, self->data->grid_y) ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
PyObject * UIGrid : : get_grid_x ( PyUIGridObject * self , void * closure ) {
return PyLong_FromLong ( self - > data - > grid_x ) ;
}
PyObject * UIGrid : : get_grid_y ( PyUIGridObject * self , void * closure ) {
return PyLong_FromLong ( self - > data - > grid_y ) ;
}
2024-04-20 10:32:04 -04:00
PyObject * UIGrid : : get_position ( PyUIGridObject * self , void * closure ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
return Py_BuildValue ( " (ff) " , self->data->position.x, self->data->position.y) ;
2024-04-20 10:32:04 -04:00
}
int UIGrid : : set_position ( PyUIGridObject * self , PyObject * value , void * closure ) {
float x , y ;
if ( ! PyArg_ParseTuple ( value , " ff " , & x , & y ) ) {
PyErr_SetString ( PyExc_ValueError , " Position must be a tuple of two floats " ) ;
return - 1 ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
self - > data - > position = sf : : Vector2f ( x , y ) ; // Update base class position
self - > data - > box . setPosition ( self - > data - > position ) ; // Sync box position
self - > data - > output . setPosition ( self - > data - > position ) ; // Sync output sprite position
2024-04-20 10:32:04 -04:00
return 0 ;
}
PyObject * UIGrid : : get_size ( PyUIGridObject * self , void * closure ) {
auto & box = self - > data - > box ;
return Py_BuildValue ( " (ff) " , box.getSize().x, box.getSize().y) ;
}
int UIGrid : : set_size ( PyUIGridObject * self , PyObject * value , void * closure ) {
float w , h ;
if ( ! PyArg_ParseTuple ( value , " ff " , & w , & h ) ) {
PyErr_SetString ( PyExc_ValueError , " Size must be a tuple of two floats " ) ;
return - 1 ;
}
self - > data - > box . setSize ( sf : : Vector2f ( w , h ) ) ;
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
// Recreate renderTexture with new size to avoid rendering issues
// Add some padding to handle zoom and ensure we don't cut off content
unsigned int tex_width = static_cast < unsigned int > ( w * 1.5f ) ;
unsigned int tex_height = static_cast < unsigned int > ( h * 1.5f ) ;
// Clamp to reasonable maximum to avoid GPU memory issues
tex_width = std : : min ( tex_width , 4096u ) ;
tex_height = std : : min ( tex_height , 4096u ) ;
self - > data - > renderTexture . create ( tex_width , tex_height ) ;
2024-04-20 10:32:04 -04:00
return 0 ;
}
PyObject * UIGrid : : get_center ( PyUIGridObject * self , void * closure ) {
return Py_BuildValue ( " (ff) " , self->data->center_x, self->data->center_y) ;
}
int UIGrid : : set_center ( PyUIGridObject * self , PyObject * value , void * closure ) {
float x , y ;
if ( ! PyArg_ParseTuple ( value , " ff " , & x , & y ) ) {
PyErr_SetString ( PyExc_ValueError , " Size must be a tuple of two floats " ) ;
return - 1 ;
}
self - > data - > center_x = x ;
self - > data - > center_y = y ;
return 0 ;
}
PyObject * UIGrid : : get_float_member ( PyUIGridObject * self , void * closure )
{
auto member_ptr = reinterpret_cast < long > ( closure ) ;
if ( member_ptr = = 0 ) // x
return PyFloat_FromDouble ( self - > data - > box . getPosition ( ) . x ) ;
else if ( member_ptr = = 1 ) // y
return PyFloat_FromDouble ( self - > data - > box . getPosition ( ) . y ) ;
else if ( member_ptr = = 2 ) // w
return PyFloat_FromDouble ( self - > data - > box . getSize ( ) . x ) ;
else if ( member_ptr = = 3 ) // h
return PyFloat_FromDouble ( self - > data - > box . getSize ( ) . y ) ;
else if ( member_ptr = = 4 ) // center_x
return PyFloat_FromDouble ( self - > data - > center_x ) ;
else if ( member_ptr = = 5 ) // center_y
return PyFloat_FromDouble ( self - > data - > center_y ) ;
else if ( member_ptr = = 6 ) // zoom
return PyFloat_FromDouble ( self - > data - > zoom ) ;
else
{
PyErr_SetString ( PyExc_AttributeError , " Invalid attribute " ) ;
return nullptr ;
}
}
int UIGrid : : set_float_member ( PyUIGridObject * self , PyObject * value , void * closure )
{
float val ;
auto member_ptr = reinterpret_cast < long > ( closure ) ;
if ( PyFloat_Check ( value ) )
{
val = PyFloat_AsDouble ( value ) ;
}
else if ( PyLong_Check ( value ) )
{
val = PyLong_AsLong ( value ) ;
}
else
{
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
PyErr_SetString ( PyExc_TypeError , " Value must be a number (int or float) " ) ;
2024-04-20 10:32:04 -04:00
return - 1 ;
}
if ( member_ptr = = 0 ) // x
self - > data - > box . setPosition ( val , self - > data - > box . getPosition ( ) . y ) ;
else if ( member_ptr = = 1 ) // y
self - > data - > box . setPosition ( self - > data - > box . getPosition ( ) . x , val ) ;
else if ( member_ptr = = 2 ) // w
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
{
2024-04-20 10:32:04 -04:00
self - > data - > box . setSize ( sf : : Vector2f ( val , self - > data - > box . getSize ( ) . y ) ) ;
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
// Recreate renderTexture when width changes
unsigned int tex_width = static_cast < unsigned int > ( val * 1.5f ) ;
unsigned int tex_height = static_cast < unsigned int > ( self - > data - > box . getSize ( ) . y * 1.5f ) ;
tex_width = std : : min ( tex_width , 4096u ) ;
tex_height = std : : min ( tex_height , 4096u ) ;
self - > data - > renderTexture . create ( tex_width , tex_height ) ;
}
2024-04-20 10:32:04 -04:00
else if ( member_ptr = = 3 ) // h
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
{
2024-04-20 10:32:04 -04:00
self - > data - > box . setSize ( sf : : Vector2f ( self - > data - > box . getSize ( ) . x , val ) ) ;
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
// Recreate renderTexture when height changes
unsigned int tex_width = static_cast < unsigned int > ( self - > data - > box . getSize ( ) . x * 1.5f ) ;
unsigned int tex_height = static_cast < unsigned int > ( val * 1.5f ) ;
tex_width = std : : min ( tex_width , 4096u ) ;
tex_height = std : : min ( tex_height , 4096u ) ;
self - > data - > renderTexture . create ( tex_width , tex_height ) ;
}
2024-04-20 10:32:04 -04:00
else if ( member_ptr = = 4 ) // center_x
self - > data - > center_x = val ;
else if ( member_ptr = = 5 ) // center_y
self - > data - > center_y = val ;
else if ( member_ptr = = 6 ) // zoom
self - > data - > zoom = val ;
return 0 ;
}
// TODO (7DRL Day 2, item 5.) return Texture object
/*
PyObject * UIGrid : : get_texture ( PyUIGridObject * self , void * closure ) {
Py_INCREF ( self - > texture ) ;
return self - > texture ;
}
*/
PyObject * UIGrid : : get_texture ( PyUIGridObject * self , void * closure ) {
//return self->data->getTexture()->pyObject();
// PyObject_GetAttrString(McRFPy_API::mcrf_module, "GridPointState")
//PyTextureObject* obj = (PyTextureObject*)((&PyTextureType)->tp_alloc(&PyTextureType, 0));
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Return None if no texture
auto texture = self - > data - > getTexture ( ) ;
if ( ! texture ) {
Py_RETURN_NONE ;
}
2024-04-20 10:32:04 -04:00
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Texture " ) ;
auto obj = ( PyTextureObject * ) type - > tp_alloc ( type , 0 ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
obj - > data = texture ;
2024-04-20 10:32:04 -04:00
return ( PyObject * ) obj ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
PyObject * UIGrid : : py_at ( PyUIGridObject * self , PyObject * args , PyObject * kwds )
2024-04-20 10:32:04 -04:00
{
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
static const char * keywords [ ] = { " x " , " y " , nullptr } ;
int x = 0 , y = 0 ;
// First try to parse as two integers
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " ii " , const_cast < char * * > ( keywords ) , & x , & y ) ) {
PyErr_Clear ( ) ;
// Try to parse as a single tuple argument
PyObject * pos_tuple = nullptr ;
if ( PyArg_ParseTuple ( args , " O " , & pos_tuple ) ) {
if ( PyTuple_Check ( pos_tuple ) & & PyTuple_Size ( pos_tuple ) = = 2 ) {
PyObject * x_obj = PyTuple_GetItem ( pos_tuple , 0 ) ;
PyObject * y_obj = PyTuple_GetItem ( pos_tuple , 1 ) ;
if ( PyLong_Check ( x_obj ) & & PyLong_Check ( y_obj ) ) {
x = PyLong_AsLong ( x_obj ) ;
y = PyLong_AsLong ( y_obj ) ;
} else {
PyErr_SetString ( PyExc_TypeError , " Grid indices must be integers " ) ;
return NULL ;
}
} else {
PyErr_SetString ( PyExc_TypeError , " at() takes two integers or a tuple of two integers " ) ;
return NULL ;
}
} else {
PyErr_SetString ( PyExc_TypeError , " at() takes two integers or a tuple of two integers " ) ;
return NULL ;
}
2024-04-20 10:32:04 -04:00
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Range validation
2024-04-20 10:32:04 -04:00
if ( x < 0 | | x > = self - > data - > grid_x ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
PyErr_Format ( PyExc_IndexError , " x index %d is out of range [0, %d) " , x , self - > data - > grid_x ) ;
2024-04-20 10:32:04 -04:00
return NULL ;
}
if ( y < 0 | | y > = self - > data - > grid_y ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
PyErr_Format ( PyExc_IndexError , " y index %d is out of range [0, %d) " , y , self - > data - > grid_y ) ;
2024-04-20 10:32:04 -04:00
return NULL ;
}
//PyUIGridPointObject* obj = (PyUIGridPointObject*)((&PyUIGridPointType)->tp_alloc(&PyUIGridPointType, 0));
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " GridPoint " ) ;
auto obj = ( PyUIGridPointObject * ) type - > tp_alloc ( type , 0 ) ;
//auto target = std::static_pointer_cast<UIEntity>(target);
obj - > data = & ( self - > data - > points [ x + self - > data - > grid_x * y ] ) ;
obj - > grid = self - > data ;
return ( PyObject * ) obj ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
PyObject * UIGrid : : get_fill_color ( PyUIGridObject * self , void * closure )
{
auto & color = self - > data - > fill_color ;
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Color " ) ;
PyObject * args = Py_BuildValue ( " (iiii) " , color . r , color . g , color . b , color . a ) ;
PyObject * obj = PyObject_CallObject ( ( PyObject * ) type , args ) ;
Py_DECREF ( args ) ;
Py_DECREF ( type ) ;
return obj ;
}
int UIGrid : : set_fill_color ( PyUIGridObject * self , PyObject * value , void * closure )
{
if ( ! PyObject_IsInstance ( value , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Color " ) ) ) {
PyErr_SetString ( PyExc_TypeError , " fill_color must be a Color object " ) ;
return - 1 ;
}
PyColorObject * color = ( PyColorObject * ) value ;
self - > data - > fill_color = color - > data ;
return 0 ;
}
PyObject * UIGrid : : get_perspective ( PyUIGridObject * self , void * closure )
{
return PyLong_FromLong ( self - > data - > perspective ) ;
}
int UIGrid : : set_perspective ( PyUIGridObject * self , PyObject * value , void * closure )
{
long perspective = PyLong_AsLong ( value ) ;
if ( PyErr_Occurred ( ) ) {
return - 1 ;
}
// Validate perspective (-1 for omniscient, or valid entity index)
if ( perspective < - 1 ) {
PyErr_SetString ( PyExc_ValueError , " perspective must be -1 (omniscient) or a valid entity index " ) ;
return - 1 ;
}
// Check if entity index is valid (if not omniscient)
if ( perspective > = 0 & & self - > data - > entities ) {
int entity_count = self - > data - > entities - > size ( ) ;
if ( perspective > = entity_count ) {
PyErr_Format ( PyExc_IndexError , " perspective index %ld out of range (grid has %d entities) " ,
perspective , entity_count ) ;
return - 1 ;
}
}
self - > data - > perspective = perspective ;
return 0 ;
}
// Python API implementations for TCOD functionality
PyObject * UIGrid : : py_compute_fov ( PyUIGridObject * self , PyObject * args , PyObject * kwds )
{
static char * kwlist [ ] = { " x " , " y " , " radius " , " light_walls " , " algorithm " , NULL } ;
int x , y , radius = 0 ;
int light_walls = 1 ;
int algorithm = FOV_BASIC ;
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " ii|ipi " , kwlist ,
& x , & y , & radius , & light_walls , & algorithm ) ) {
return NULL ;
}
self - > data - > computeFOV ( x , y , radius , light_walls , ( TCOD_fov_algorithm_t ) algorithm ) ;
Py_RETURN_NONE ;
}
PyObject * UIGrid : : py_is_in_fov ( PyUIGridObject * self , PyObject * args )
{
int x , y ;
if ( ! PyArg_ParseTuple ( args , " ii " , & x , & y ) ) {
return NULL ;
}
bool in_fov = self - > data - > isInFOV ( x , y ) ;
return PyBool_FromLong ( in_fov ) ;
}
PyObject * UIGrid : : py_find_path ( PyUIGridObject * self , PyObject * args , PyObject * kwds )
{
static char * kwlist [ ] = { " x1 " , " y1 " , " x2 " , " y2 " , " diagonal_cost " , NULL } ;
int x1 , y1 , x2 , y2 ;
float diagonal_cost = 1.41f ;
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " iiii|f " , kwlist ,
& x1 , & y1 , & x2 , & y2 , & diagonal_cost ) ) {
return NULL ;
}
std : : vector < std : : pair < int , int > > path = self - > data - > findPath ( x1 , y1 , x2 , y2 , diagonal_cost ) ;
PyObject * path_list = PyList_New ( path . size ( ) ) ;
if ( ! path_list ) return NULL ;
for ( size_t i = 0 ; i < path . size ( ) ; i + + ) {
PyObject * coord = Py_BuildValue ( " (ii) " , path [ i ] . first , path [ i ] . second ) ;
if ( ! coord ) {
Py_DECREF ( path_list ) ;
return NULL ;
}
PyList_SET_ITEM ( path_list , i , coord ) ;
}
return path_list ;
}
PyObject * UIGrid : : py_compute_dijkstra ( PyUIGridObject * self , PyObject * args , PyObject * kwds )
{
static char * kwlist [ ] = { " root_x " , " root_y " , " diagonal_cost " , NULL } ;
int root_x , root_y ;
float diagonal_cost = 1.41f ;
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " ii|f " , kwlist ,
& root_x , & root_y , & diagonal_cost ) ) {
return NULL ;
}
self - > data - > computeDijkstra ( root_x , root_y , diagonal_cost ) ;
Py_RETURN_NONE ;
}
PyObject * UIGrid : : py_get_dijkstra_distance ( PyUIGridObject * self , PyObject * args )
{
int x , y ;
if ( ! PyArg_ParseTuple ( args , " ii " , & x , & y ) ) {
return NULL ;
}
float distance = self - > data - > getDijkstraDistance ( x , y ) ;
if ( distance < 0 ) {
Py_RETURN_NONE ; // Invalid position
}
return PyFloat_FromDouble ( distance ) ;
}
PyObject * UIGrid : : py_get_dijkstra_path ( PyUIGridObject * self , PyObject * args )
{
int x , y ;
if ( ! PyArg_ParseTuple ( args , " ii " , & x , & y ) ) {
return NULL ;
}
std : : vector < std : : pair < int , int > > path = self - > data - > getDijkstraPath ( x , y ) ;
PyObject * path_list = PyList_New ( path . size ( ) ) ;
for ( size_t i = 0 ; i < path . size ( ) ; i + + ) {
PyObject * pos = Py_BuildValue ( " (ii) " , path [ i ] . first , path [ i ] . second ) ;
PyList_SetItem ( path_list , i , pos ) ; // Steals reference
}
return path_list ;
}
PyObject * UIGrid : : py_compute_astar_path ( PyUIGridObject * self , PyObject * args , PyObject * kwds )
{
int x1 , y1 , x2 , y2 ;
float diagonal_cost = 1.41f ;
static char * kwlist [ ] = { " x1 " , " y1 " , " x2 " , " y2 " , " diagonal_cost " , NULL } ;
if ( ! PyArg_ParseTupleAndKeywords ( args , kwds , " iiii|f " , kwlist ,
& x1 , & y1 , & x2 , & y2 , & diagonal_cost ) ) {
return NULL ;
}
// Compute A* path
std : : vector < std : : pair < int , int > > path = self - > data - > computeAStarPath ( x1 , y1 , x2 , y2 , diagonal_cost ) ;
// Convert to Python list
PyObject * path_list = PyList_New ( path . size ( ) ) ;
for ( size_t i = 0 ; i < path . size ( ) ; i + + ) {
PyObject * pos = Py_BuildValue ( " (ii) " , path [ i ] . first , path [ i ] . second ) ;
PyList_SetItem ( path_list , i , pos ) ; // Steals reference
}
return path_list ;
}
2024-04-20 10:32:04 -04:00
PyMethodDef UIGrid : : methods [ ] = {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
{ " at " , ( PyCFunction ) UIGrid : : py_at , METH_VARARGS | METH_KEYWORDS } ,
{ " compute_fov " , ( PyCFunction ) UIGrid : : py_compute_fov , METH_VARARGS | METH_KEYWORDS ,
" Compute field of view from a position. Args: x, y, radius=0, light_walls=True, algorithm=FOV_BASIC " } ,
{ " is_in_fov " , ( PyCFunction ) UIGrid : : py_is_in_fov , METH_VARARGS ,
" Check if a cell is in the field of view. Args: x, y " } ,
{ " find_path " , ( PyCFunction ) UIGrid : : py_find_path , METH_VARARGS | METH_KEYWORDS ,
" Find A* path between two points. Args: x1, y1, x2, y2, diagonal_cost=1.41 " } ,
{ " compute_dijkstra " , ( PyCFunction ) UIGrid : : py_compute_dijkstra , METH_VARARGS | METH_KEYWORDS ,
" Compute Dijkstra map from root position. Args: root_x, root_y, diagonal_cost=1.41 " } ,
{ " get_dijkstra_distance " , ( PyCFunction ) UIGrid : : py_get_dijkstra_distance , METH_VARARGS ,
" Get distance from Dijkstra root to position. Args: x, y. Returns float or None if invalid. " } ,
{ " get_dijkstra_path " , ( PyCFunction ) UIGrid : : py_get_dijkstra_path , METH_VARARGS ,
" Get path from position to Dijkstra root. Args: x, y. Returns list of (x,y) tuples. " } ,
{ " compute_astar_path " , ( PyCFunction ) UIGrid : : py_compute_astar_path , METH_VARARGS | METH_KEYWORDS ,
" Compute A* path between two points. Args: x1, y1, x2, y2, diagonal_cost=1.41. Returns list of (x,y) tuples. Note: diagonal_cost is currently ignored (uses default 1.41). " } ,
2024-04-20 10:32:04 -04:00
{ NULL , NULL , 0 , NULL }
} ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Define the PyObjectType alias for the macros
typedef PyUIGridObject PyObjectType ;
// Combined methods array
PyMethodDef UIGrid_all_methods [ ] = {
UIDRAWABLE_METHODS ,
{ " at " , ( PyCFunction ) UIGrid : : py_at , METH_VARARGS | METH_KEYWORDS } ,
{ " compute_fov " , ( PyCFunction ) UIGrid : : py_compute_fov , METH_VARARGS | METH_KEYWORDS ,
" Compute field of view from a position. Args: x, y, radius=0, light_walls=True, algorithm=FOV_BASIC " } ,
{ " is_in_fov " , ( PyCFunction ) UIGrid : : py_is_in_fov , METH_VARARGS ,
" Check if a cell is in the field of view. Args: x, y " } ,
{ " find_path " , ( PyCFunction ) UIGrid : : py_find_path , METH_VARARGS | METH_KEYWORDS ,
" Find A* path between two points. Args: x1, y1, x2, y2, diagonal_cost=1.41 " } ,
{ " compute_dijkstra " , ( PyCFunction ) UIGrid : : py_compute_dijkstra , METH_VARARGS | METH_KEYWORDS ,
" Compute Dijkstra map from root position. Args: root_x, root_y, diagonal_cost=1.41 " } ,
{ " get_dijkstra_distance " , ( PyCFunction ) UIGrid : : py_get_dijkstra_distance , METH_VARARGS ,
" Get distance from Dijkstra root to position. Args: x, y. Returns float or None if invalid. " } ,
{ " get_dijkstra_path " , ( PyCFunction ) UIGrid : : py_get_dijkstra_path , METH_VARARGS ,
" Get path from position to Dijkstra root. Args: x, y. Returns list of (x,y) tuples. " } ,
{ " compute_astar_path " , ( PyCFunction ) UIGrid : : py_compute_astar_path , METH_VARARGS | METH_KEYWORDS ,
" Compute A* path between two points. Args: x1, y1, x2, y2, diagonal_cost=1.41. Returns list of (x,y) tuples. Note: diagonal_cost is currently ignored (uses default 1.41). " } ,
{ NULL } // Sentinel
} ;
2024-04-20 10:32:04 -04:00
PyGetSetDef UIGrid : : getsetters [ ] = {
// TODO - refactor into get_vector_member with field identifier values `(void*)n`
{ " grid_size " , ( getter ) UIGrid : : get_grid_size , NULL , " Grid dimensions (grid_x, grid_y) " , NULL } ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
{ " grid_x " , ( getter ) UIGrid : : get_grid_x , NULL , " Grid x dimension " , NULL } ,
{ " grid_y " , ( getter ) UIGrid : : get_grid_y , NULL , " Grid y dimension " , NULL } ,
2024-04-20 10:32:04 -04:00
{ " position " , ( getter ) UIGrid : : get_position , ( setter ) UIGrid : : set_position , " Position of the grid (x, y) " , NULL } ,
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
{ " pos " , ( getter ) UIDrawable : : get_pos , ( setter ) UIDrawable : : set_pos , " Position of the grid as Vector " , ( void * ) PyObjectsEnum : : UIGRID } ,
2024-04-20 10:32:04 -04:00
{ " size " , ( getter ) UIGrid : : get_size , ( setter ) UIGrid : : set_size , " Size of the grid (width, height) " , NULL } ,
{ " center " , ( getter ) UIGrid : : get_center , ( setter ) UIGrid : : set_center , " Grid coordinate at the center of the Grid's view (pan) " , NULL } ,
{ " entities " , ( getter ) UIGrid : : get_children , NULL , " EntityCollection of entities on this grid " , NULL } ,
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
{ " x " , ( getter ) UIDrawable : : get_float_member , ( setter ) UIDrawable : : set_float_member , " top-left corner X-coordinate " , ( void * ) ( ( intptr_t ) PyObjectsEnum : : UIGRID < < 8 | 0 ) } ,
{ " y " , ( getter ) UIDrawable : : get_float_member , ( setter ) UIDrawable : : set_float_member , " top-left corner Y-coordinate " , ( void * ) ( ( intptr_t ) PyObjectsEnum : : UIGRID < < 8 | 1 ) } ,
{ " w " , ( getter ) UIDrawable : : get_float_member , ( setter ) UIDrawable : : set_float_member , " visible widget width " , ( void * ) ( ( intptr_t ) PyObjectsEnum : : UIGRID < < 8 | 2 ) } ,
{ " h " , ( getter ) UIDrawable : : get_float_member , ( setter ) UIDrawable : : set_float_member , " visible widget height " , ( void * ) ( ( intptr_t ) PyObjectsEnum : : UIGRID < < 8 | 3 ) } ,
2024-04-20 10:32:04 -04:00
{ " center_x " , ( getter ) UIGrid : : get_float_member , ( setter ) UIGrid : : set_float_member , " center of the view X-coordinate " , ( void * ) 4 } ,
{ " center_y " , ( getter ) UIGrid : : get_float_member , ( setter ) UIGrid : : set_float_member , " center of the view Y-coordinate " , ( void * ) 5 } ,
{ " zoom " , ( getter ) UIGrid : : get_float_member , ( setter ) UIGrid : : set_float_member , " zoom factor for displaying the Grid " , ( void * ) 6 } ,
{ " click " , ( getter ) UIDrawable : : get_click , ( setter ) UIDrawable : : set_click , " Object called with (x, y, button) when clicked " , ( void * ) PyObjectsEnum : : UIGRID } ,
{ " texture " , ( getter ) UIGrid : : get_texture , NULL , " Texture of the grid " , NULL } , //TODO 7DRL-day2-item5
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
{ " fill_color " , ( getter ) UIGrid : : get_fill_color , ( setter ) UIGrid : : set_fill_color , " Background fill color of the grid " , NULL } ,
{ " perspective " , ( getter ) UIGrid : : get_perspective , ( setter ) UIGrid : : set_perspective , " Entity perspective index (-1 for omniscient view) " , NULL } ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
{ " z_index " , ( getter ) UIDrawable : : get_int , ( setter ) UIDrawable : : set_int , " Z-order for rendering (lower values rendered first) " , ( void * ) PyObjectsEnum : : UIGRID } ,
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
{ " name " , ( getter ) UIDrawable : : get_name , ( setter ) UIDrawable : : set_name , " Name for finding elements " , ( void * ) PyObjectsEnum : : UIGRID } ,
UIDRAWABLE_GETSETTERS ,
2024-04-20 10:32:04 -04:00
{ NULL } /* Sentinel */
} ;
PyObject * UIGrid : : get_children ( PyUIGridObject * self , void * closure )
{
// create PyUICollection instance pointing to self->data->children
//PyUIEntityCollectionObject* o = (PyUIEntityCollectionObject*)PyUIEntityCollectionType.tp_alloc(&PyUIEntityCollectionType, 0);
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " EntityCollection " ) ;
auto o = ( PyUIEntityCollectionObject * ) type - > tp_alloc ( type , 0 ) ;
if ( o ) {
o - > data = self - > data - > entities ; // todone. / BUGFIX - entities isn't a shared pointer on UIGrid, what to do? -- I made it a sp<list<sp<UIEntity>>>
o - > grid = self - > data ;
}
return ( PyObject * ) o ;
}
2024-04-20 18:33:18 -04:00
PyObject * UIGrid : : repr ( PyUIGridObject * self )
{
std : : ostringstream ss ;
if ( ! self - > data ) ss < < " <Grid (invalid internal object)> " ;
else {
auto grid = self - > data ;
auto box = grid - > box ;
ss < < " <Grid (x= " < < box . getPosition ( ) . x < < " , y= " < < box . getPosition ( ) . y < < " , w= " < < box . getSize ( ) . x < < " , h= " < < box . getSize ( ) . y < < " , " < <
" center=( " < < grid - > center_x < < " , " < < grid - > center_y < < " ), zoom= " < < grid - > zoom < <
" )> " ;
}
std : : string repr_str = ss . str ( ) ;
return PyUnicode_DecodeUTF8 ( repr_str . c_str ( ) , repr_str . size ( ) , " replace " ) ;
}
2024-04-20 10:32:04 -04:00
/* // TODO standard pointer would need deleted, but I opted for a shared pointer. tp_dealloc currently not even defined in the PyTypeObject
void PyUIGrid_dealloc ( PyUIGridObject * self ) {
delete self - > data ; // Clean up the allocated UIGrid object
Py_TYPE ( self ) - > tp_free ( ( PyObject * ) self ) ;
}
*/
int UIEntityCollectionIter : : init ( PyUIEntityCollectionIterObject * self , PyObject * args , PyObject * kwds )
{
PyErr_SetString ( PyExc_TypeError , " UICollection cannot be instantiated: a C++ data source is required. " ) ;
return - 1 ;
}
PyObject * UIEntityCollectionIter : : next ( PyUIEntityCollectionIterObject * self )
{
if ( self - > data - > size ( ) ! = self - > start_size )
{
PyErr_SetString ( PyExc_RuntimeError , " collection changed size during iteration " ) ;
return NULL ;
}
if ( self - > index > self - > start_size - 1 )
{
PyErr_SetNone ( PyExc_StopIteration ) ;
return NULL ;
}
self - > index + + ;
auto vec = self - > data . get ( ) ;
if ( ! vec )
{
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return NULL ;
}
Iterators, other Python C API improvements
closes #72
ref #69 - this resolves the "UICollection" (not "UIEntityCollection", perhaps renamed since the issue opened) and "UIEntityCollection" portion. The Grid point based iterators were not updated.
**RPATH updates**
Will this RPATH setting allow McRogueFace to execute using its included "lib" subdirectory after being unzipped on a new computer?
The change from "./lib" to "$ORIGIN/./lib" improves portability. The $ORIGIN token is a special Linux/Unix convention that refers to the directory containing the executable itself. This makes the path relative to the executable's location rather than the current working directory, which means McRogueFace will correctly find its libraries in the lib subdirectory regardless of where it's run from after being unzipped on a new computer.
**New standard object initialization**
PyColor, PyVector
- Fixed all 15 PyTypeObject definitions to use proper designated initializer syntax
- Replaced PyType_GenericAlloc usage in PyColor.cpp and PyVector.cpp
- Updated PyObject_New usage in UIEntity.cpp
- All object creation now uses module-based type lookups instead of static references
- Created centralized utilities in PyObjectUtils.h
**RAII Wrappers**
automatic reference counting via C++ object lifecycle
- Created PyRAII.h with PyObjectRef and PyTypeRef classes
- These provide automatic reference counting management
- Updated PyColor::from_arg() to demonstrate RAII usage
- Prevents memory leaks and reference counting errors
**Python object base in type defs:**
`.ob_base = {.ob_base = {.ob_refcnt = 1, .ob_type = NULL}, .ob_size = 0}`
PyColor, PyTexture, PyVector, UICaption, UICollection, UIEntity, UIFrame, UIGrid
**convertDrawableToPython**
replace crazy macro to detect the correct Python type of a UIDrawable instance
- Removed the problematic macro from UIDrawable.h
- Created template-based functions in PyObjectUtils.h
- Updated UICollection.cpp to use local helper function
- The new approach is cleaner, more debuggable, and avoids static type references
**Iterator fixes**
tp_iter on UICollection, UIGrid, UIGridPoint, UISprite
UIGrid logic improved, standard
**List vs Vector usage analysis**
there are different use cases that weren't standardized:
- UICollection (for Frame children) uses std::vector<std::shared_ptr<UIDrawable>>
- UIEntityCollection (for Grid entities) uses std::list<std::shared_ptr<UIEntity>>
The rationale is currently connected to frequency of expected changes.
* A "UICollection" is likely either all visible or not; it's also likely to be created once and have a static set of contents. They should be contiguous in memory in hopes that this helps rendering speed.
* A "UIEntityCollection" is expected to be rendered as a subset within the visible rectangle of the UIGrid. Scrolling the grid or gameplay logic is likely to frequently create and destroy entities. In general I expect Entity collections to have a much higher common size than UICollections. For these reasons I've made them Lists in hopes that they never have to be reallocated or moved during a frame.
2025-05-31 08:58:52 -04:00
// Advance list iterator since Entities are stored in a list, not a vector
auto l_begin = ( * vec ) . begin ( ) ;
std : : advance ( l_begin , self - > index - 1 ) ;
auto target = * l_begin ;
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
// Return the stored Python object if it exists (preserves derived types)
if ( target - > self ! = nullptr ) {
Py_INCREF ( target - > self ) ;
return target - > self ;
}
// Otherwise create and return a new Python Entity object
Iterators, other Python C API improvements
closes #72
ref #69 - this resolves the "UICollection" (not "UIEntityCollection", perhaps renamed since the issue opened) and "UIEntityCollection" portion. The Grid point based iterators were not updated.
**RPATH updates**
Will this RPATH setting allow McRogueFace to execute using its included "lib" subdirectory after being unzipped on a new computer?
The change from "./lib" to "$ORIGIN/./lib" improves portability. The $ORIGIN token is a special Linux/Unix convention that refers to the directory containing the executable itself. This makes the path relative to the executable's location rather than the current working directory, which means McRogueFace will correctly find its libraries in the lib subdirectory regardless of where it's run from after being unzipped on a new computer.
**New standard object initialization**
PyColor, PyVector
- Fixed all 15 PyTypeObject definitions to use proper designated initializer syntax
- Replaced PyType_GenericAlloc usage in PyColor.cpp and PyVector.cpp
- Updated PyObject_New usage in UIEntity.cpp
- All object creation now uses module-based type lookups instead of static references
- Created centralized utilities in PyObjectUtils.h
**RAII Wrappers**
automatic reference counting via C++ object lifecycle
- Created PyRAII.h with PyObjectRef and PyTypeRef classes
- These provide automatic reference counting management
- Updated PyColor::from_arg() to demonstrate RAII usage
- Prevents memory leaks and reference counting errors
**Python object base in type defs:**
`.ob_base = {.ob_base = {.ob_refcnt = 1, .ob_type = NULL}, .ob_size = 0}`
PyColor, PyTexture, PyVector, UICaption, UICollection, UIEntity, UIFrame, UIGrid
**convertDrawableToPython**
replace crazy macro to detect the correct Python type of a UIDrawable instance
- Removed the problematic macro from UIDrawable.h
- Created template-based functions in PyObjectUtils.h
- Updated UICollection.cpp to use local helper function
- The new approach is cleaner, more debuggable, and avoids static type references
**Iterator fixes**
tp_iter on UICollection, UIGrid, UIGridPoint, UISprite
UIGrid logic improved, standard
**List vs Vector usage analysis**
there are different use cases that weren't standardized:
- UICollection (for Frame children) uses std::vector<std::shared_ptr<UIDrawable>>
- UIEntityCollection (for Grid entities) uses std::list<std::shared_ptr<UIEntity>>
The rationale is currently connected to frequency of expected changes.
* A "UICollection" is likely either all visible or not; it's also likely to be created once and have a static set of contents. They should be contiguous in memory in hopes that this helps rendering speed.
* A "UIEntityCollection" is expected to be rendered as a subset within the visible rectangle of the UIGrid. Scrolling the grid or gameplay logic is likely to frequently create and destroy entities. In general I expect Entity collections to have a much higher common size than UICollections. For these reasons I've made them Lists in hopes that they never have to be reallocated or moved during a frame.
2025-05-31 08:58:52 -04:00
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ;
auto o = ( PyUIEntityObject * ) type - > tp_alloc ( type , 0 ) ;
auto p = std : : static_pointer_cast < UIEntity > ( target ) ;
o - > data = p ;
return ( PyObject * ) o ;
2024-04-20 10:32:04 -04:00
}
PyObject * UIEntityCollectionIter : : repr ( PyUIEntityCollectionIterObject * self )
{
std : : ostringstream ss ;
if ( ! self - > data ) ss < < " <UICollectionIter (invalid internal object)> " ;
else {
ss < < " <UICollectionIter ( " < < self - > data - > size ( ) < < " child objects, @ index " < < self - > index < < " )> " ;
}
std : : string repr_str = ss . str ( ) ;
return PyUnicode_DecodeUTF8 ( repr_str . c_str ( ) , repr_str . size ( ) , " replace " ) ;
}
Py_ssize_t UIEntityCollection : : len ( PyUIEntityCollectionObject * self ) {
return self - > data - > size ( ) ;
}
PyObject * UIEntityCollection : : getitem ( PyUIEntityCollectionObject * self , Py_ssize_t index ) {
// build a Python version of item at self->data[index]
// Copy pasted::
auto vec = self - > data . get ( ) ;
if ( ! vec )
{
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return NULL ;
}
while ( index < 0 ) index + = self - > data - > size ( ) ;
if ( index > self - > data - > size ( ) - 1 )
{
PyErr_SetString ( PyExc_IndexError , " EntityCollection index out of range " ) ;
return NULL ;
}
auto l_begin = ( * vec ) . begin ( ) ;
std : : advance ( l_begin , index ) ;
auto target = * l_begin ; //auto target = (*vec)[index];
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
// If the entity has a stored Python object reference, return that to preserve derived class
if ( target - > self ! = nullptr ) {
Py_INCREF ( target - > self ) ;
return target - > self ;
}
// Otherwise, create a new base Entity object
2024-04-20 10:32:04 -04:00
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ;
auto o = ( PyUIEntityObject * ) type - > tp_alloc ( type , 0 ) ;
auto p = std : : static_pointer_cast < UIEntity > ( target ) ;
o - > data = p ;
return ( PyObject * ) o ;
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
}
2024-04-20 10:32:04 -04:00
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
int UIEntityCollection : : setitem ( PyUIEntityCollectionObject * self , Py_ssize_t index , PyObject * value ) {
auto list = self - > data . get ( ) ;
if ( ! list ) {
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return - 1 ;
}
// Handle negative indexing
while ( index < 0 ) index + = list - > size ( ) ;
// Bounds check
if ( index > = list - > size ( ) ) {
PyErr_SetString ( PyExc_IndexError , " EntityCollection assignment index out of range " ) ;
return - 1 ;
}
// Get iterator to the target position
auto it = list - > begin ( ) ;
std : : advance ( it , index ) ;
// Handle deletion
if ( value = = NULL ) {
// Clear grid reference from the entity being removed
( * it ) - > grid = nullptr ;
list - > erase ( it ) ;
return 0 ;
}
// Type checking - must be an Entity
if ( ! PyObject_IsInstance ( value , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
PyErr_SetString ( PyExc_TypeError , " EntityCollection can only contain Entity objects " ) ;
return - 1 ;
}
// Get the C++ object from the Python object
PyUIEntityObject * entity = ( PyUIEntityObject * ) value ;
if ( ! entity - > data ) {
PyErr_SetString ( PyExc_RuntimeError , " Invalid Entity object " ) ;
return - 1 ;
}
// Clear grid reference from the old entity
( * it ) - > grid = nullptr ;
// Replace the element and set grid reference
* it = entity - > data ;
entity - > data - > grid = self - > grid ;
return 0 ;
}
2024-04-20 10:32:04 -04:00
Squashed commit of the following: [alpha_streamline_1]
the low-hanging fruit of pre-existing issues and standardizing the
Python interfaces
Special thanks to Claude Code, ~100k output tokens for this merge
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 99f301e3a0e9e81ad28c9e1d410390c32dfd933c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:25:32 2025 -0400
Add position tuple support and pos property to UI elements
closes #83, closes #84
- Issue #83: Add position tuple support to constructors
- Frame and Sprite now accept both (x, y) and ((x, y)) forms
- Also accept Vector objects as position arguments
- Caption and Entity already supported tuple/Vector forms
- Uses PyVector::from_arg for flexible position parsing
- Issue #84: Add pos property to Frame and Sprite
- Added pos getter that returns a Vector
- Added pos setter that accepts Vector or tuple
- Provides consistency with Caption and Entity which already had pos properties
- All UI elements now have a uniform way to get/set positions as Vectors
Both features improve API consistency and make it easier to work with positions.
commit 2f2b488fb54da12c39c0010dbd83cb9f6c429b01
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:18:10 2025 -0400
Standardize sprite_index property and add scale_x/scale_y to UISprite
closes #81, closes #82
- Issue #81: Standardized property name to sprite_index across UISprite and UIEntity
- Added sprite_index as the primary property name
- Kept sprite_number as a deprecated alias for backward compatibility
- Updated repr() methods to use sprite_index
- Updated animation system to recognize both names
- Issue #82: Added scale_x and scale_y properties to UISprite
- Enables non-uniform scaling of sprites
- scale property still works for uniform scaling
- Both properties work with the animation system
All existing code using sprite_number continues to work due to backward compatibility.
commit 5a003a9aa587eb8ee4b79ac67ca8f342ab62e2d2
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 16:09:52 2025 -0400
Fix multiple low priority issues
closes #12, closes #80, closes #95, closes #96, closes #99
- Issue #12: Set tp_new to NULL for GridPoint and GridPointState to prevent instantiation from Python
- Issue #80: Renamed Caption.size to Caption.font_size for semantic clarity
- Issue #95: Fixed UICollection repr to show actual derived types instead of generic UIDrawable
- Issue #96: Added extend() method to UICollection for API consistency with UIEntityCollection
- Issue #99: Exposed read-only properties for Texture (sprite_width, sprite_height, sheet_width, sheet_height, sprite_count, source) and Font (family, source)
All issues have corresponding tests that verify the fixes work correctly.
commit e5affaf317665395135c936bc4a6b840ae321765
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 15:50:09 2025 -0400
Fix critical issues: script loading, entity types, and color properties
- Issue #37: Fix Windows scripts subdirectory not checked
- Updated executeScript() to use executable_path() from platform.h
- Scripts now load correctly when working directory differs from executable
- Issue #76: Fix UIEntityCollection returns wrong type
- Updated UIEntityCollectionIter::next() to check for stored Python object
- Derived Entity classes now preserve their type when retrieved from collections
- Issue #9: Recreate RenderTexture when resized (already fixed)
- Confirmed RenderTexture recreation already implemented in set_size() and set_float_member()
- Uses 1.5x padding and 4096 max size limit
- Issue #79: Fix Color r, g, b, a properties return None
- Implemented get_member() and set_member() in PyColor.cpp
- Color component properties now work correctly with proper validation
- Additional fix: Grid.at() method signature
- Changed from METH_O to METH_VARARGS to accept two arguments
All fixes include comprehensive tests to verify functionality.
closes #37, closes #76, closes #9, closes #79
2025-07-05 17:30:49 -04:00
int UIEntityCollection : : contains ( PyUIEntityCollectionObject * self , PyObject * value ) {
auto list = self - > data . get ( ) ;
if ( ! list ) {
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return - 1 ;
}
// Type checking - must be an Entity
if ( ! PyObject_IsInstance ( value , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
// Not an Entity, so it can't be in the collection
return 0 ;
}
// Get the C++ object from the Python object
PyUIEntityObject * entity = ( PyUIEntityObject * ) value ;
if ( ! entity - > data ) {
return 0 ;
}
// Search for the object by comparing C++ pointers
for ( const auto & ent : * list ) {
if ( ent . get ( ) = = entity - > data . get ( ) ) {
return 1 ; // Found
}
}
return 0 ; // Not found
}
PyObject * UIEntityCollection : : concat ( PyUIEntityCollectionObject * self , PyObject * other ) {
// Create a new Python list containing elements from both collections
if ( ! PySequence_Check ( other ) ) {
PyErr_SetString ( PyExc_TypeError , " can only concatenate sequence to EntityCollection " ) ;
return NULL ;
}
Py_ssize_t self_len = self - > data - > size ( ) ;
Py_ssize_t other_len = PySequence_Length ( other ) ;
if ( other_len = = - 1 ) {
return NULL ; // Error already set
}
PyObject * result_list = PyList_New ( self_len + other_len ) ;
if ( ! result_list ) {
return NULL ;
}
// Add all elements from self
Py_ssize_t idx = 0 ;
for ( const auto & entity : * self - > data ) {
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ;
auto obj = ( PyUIEntityObject * ) type - > tp_alloc ( type , 0 ) ;
if ( obj ) {
obj - > data = entity ;
PyList_SET_ITEM ( result_list , idx , ( PyObject * ) obj ) ; // Steals reference
} else {
Py_DECREF ( result_list ) ;
Py_DECREF ( type ) ;
return NULL ;
}
Py_DECREF ( type ) ;
idx + + ;
}
// Add all elements from other
for ( Py_ssize_t i = 0 ; i < other_len ; i + + ) {
PyObject * item = PySequence_GetItem ( other , i ) ;
if ( ! item ) {
Py_DECREF ( result_list ) ;
return NULL ;
}
PyList_SET_ITEM ( result_list , self_len + i , item ) ; // Steals reference
}
return result_list ;
}
PyObject * UIEntityCollection : : inplace_concat ( PyUIEntityCollectionObject * self , PyObject * other ) {
if ( ! PySequence_Check ( other ) ) {
PyErr_SetString ( PyExc_TypeError , " can only concatenate sequence to EntityCollection " ) ;
return NULL ;
}
// First, validate ALL items in the sequence before modifying anything
Py_ssize_t other_len = PySequence_Length ( other ) ;
if ( other_len = = - 1 ) {
return NULL ; // Error already set
}
// Validate all items first
for ( Py_ssize_t i = 0 ; i < other_len ; i + + ) {
PyObject * item = PySequence_GetItem ( other , i ) ;
if ( ! item ) {
return NULL ;
}
// Type check
if ( ! PyObject_IsInstance ( item , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
Py_DECREF ( item ) ;
PyErr_Format ( PyExc_TypeError ,
" EntityCollection can only contain Entity objects; "
" got %s at index %zd " , Py_TYPE ( item ) - > tp_name , i ) ;
return NULL ;
}
Py_DECREF ( item ) ;
}
// All items validated, now we can safely add them
for ( Py_ssize_t i = 0 ; i < other_len ; i + + ) {
PyObject * item = PySequence_GetItem ( other , i ) ;
if ( ! item ) {
return NULL ; // Shouldn't happen, but be safe
}
// Use the existing append method which handles grid references
PyObject * result = append ( self , item ) ;
Py_DECREF ( item ) ;
if ( ! result ) {
return NULL ; // append() failed
}
Py_DECREF ( result ) ; // append returns Py_None
}
Py_INCREF ( self ) ;
return ( PyObject * ) self ;
2024-04-20 10:32:04 -04:00
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
2024-04-20 10:32:04 -04:00
PySequenceMethods UIEntityCollection : : sqmethods = {
. sq_length = ( lenfunc ) UIEntityCollection : : len ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
. sq_concat = ( binaryfunc ) UIEntityCollection : : concat ,
. sq_repeat = NULL ,
2024-04-20 10:32:04 -04:00
. sq_item = ( ssizeargfunc ) UIEntityCollection : : getitem ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
. was_sq_slice = NULL ,
. sq_ass_item = ( ssizeobjargproc ) UIEntityCollection : : setitem ,
. was_sq_ass_slice = NULL ,
. sq_contains = ( objobjproc ) UIEntityCollection : : contains ,
. sq_inplace_concat = ( binaryfunc ) UIEntityCollection : : inplace_concat ,
. sq_inplace_repeat = NULL
2024-04-20 10:32:04 -04:00
} ;
PyObject * UIEntityCollection : : append ( PyUIEntityCollectionObject * self , PyObject * o )
{
// if not UIDrawable subclass, reject it
// self->data->push_back( c++ object inside o );
// this would be a great use case for .tp_base
//if (!PyObject_IsInstance(o, (PyObject*)&PyUIEntityType))
if ( ! PyObject_IsInstance ( o , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) )
{
PyErr_SetString ( PyExc_TypeError , " Only Entity objects can be added to EntityCollection " ) ;
return NULL ;
}
PyUIEntityObject * entity = ( PyUIEntityObject * ) o ;
self - > data - > push_back ( entity - > data ) ;
entity - > data - > grid = self - > grid ;
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
// Initialize gridstate if not already done
if ( entity - > data - > gridstate . size ( ) = = 0 & & self - > grid ) {
entity - > data - > gridstate . resize ( self - > grid - > grid_x * self - > grid - > grid_y ) ;
// Initialize all cells as not visible/discovered
for ( auto & state : entity - > data - > gridstate ) {
state . visible = false ;
state . discovered = false ;
}
}
2024-04-20 10:32:04 -04:00
Py_INCREF ( Py_None ) ;
return Py_None ;
}
PyObject * UIEntityCollection : : remove ( PyUIEntityCollectionObject * self , PyObject * o )
{
if ( ! PyLong_Check ( o ) )
{
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
PyErr_SetString ( PyExc_TypeError , " EntityCollection.remove requires an integer index to remove " ) ;
2024-04-20 10:32:04 -04:00
return NULL ;
}
long index = PyLong_AsLong ( o ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Handle negative indexing
while ( index < 0 ) index + = self - > data - > size ( ) ;
2024-04-20 10:32:04 -04:00
if ( index > = self - > data - > size ( ) )
{
PyErr_SetString ( PyExc_ValueError , " Index out of range " ) ;
return NULL ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Get iterator to the entity to remove
auto it = self - > data - > begin ( ) ;
std : : advance ( it , index ) ;
// Clear grid reference before removing
( * it ) - > grid = nullptr ;
2024-04-20 10:32:04 -04:00
// release the shared pointer at correct part of the list
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
self - > data - > erase ( it ) ;
2024-04-20 10:32:04 -04:00
Py_INCREF ( Py_None ) ;
return Py_None ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
PyObject * UIEntityCollection : : extend ( PyUIEntityCollectionObject * self , PyObject * o )
{
// Accept any iterable of Entity objects
PyObject * iterator = PyObject_GetIter ( o ) ;
if ( iterator = = NULL ) {
PyErr_SetString ( PyExc_TypeError , " UIEntityCollection.extend requires an iterable " ) ;
return NULL ;
}
PyObject * item ;
while ( ( item = PyIter_Next ( iterator ) ) ! = NULL ) {
// Check if item is an Entity
if ( ! PyObject_IsInstance ( item , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
Py_DECREF ( item ) ;
Py_DECREF ( iterator ) ;
PyErr_SetString ( PyExc_TypeError , " All items in iterable must be Entity objects " ) ;
return NULL ;
}
// Add the entity to the collection
PyUIEntityObject * entity = ( PyUIEntityObject * ) item ;
self - > data - > push_back ( entity - > data ) ;
entity - > data - > grid = self - > grid ;
Py_DECREF ( item ) ;
}
Py_DECREF ( iterator ) ;
// Check if iteration ended due to an error
if ( PyErr_Occurred ( ) ) {
return NULL ;
}
Py_INCREF ( Py_None ) ;
return Py_None ;
}
PyObject * UIEntityCollection : : index_method ( PyUIEntityCollectionObject * self , PyObject * value ) {
auto list = self - > data . get ( ) ;
if ( ! list ) {
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return NULL ;
}
// Type checking - must be an Entity
if ( ! PyObject_IsInstance ( value , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
PyErr_SetString ( PyExc_TypeError , " EntityCollection.index requires an Entity object " ) ;
return NULL ;
}
// Get the C++ object from the Python object
PyUIEntityObject * entity = ( PyUIEntityObject * ) value ;
if ( ! entity - > data ) {
PyErr_SetString ( PyExc_RuntimeError , " Invalid Entity object " ) ;
return NULL ;
}
// Search for the object
Py_ssize_t idx = 0 ;
for ( const auto & ent : * list ) {
if ( ent . get ( ) = = entity - > data . get ( ) ) {
return PyLong_FromSsize_t ( idx ) ;
}
idx + + ;
}
PyErr_SetString ( PyExc_ValueError , " Entity not in EntityCollection " ) ;
return NULL ;
}
PyObject * UIEntityCollection : : count ( PyUIEntityCollectionObject * self , PyObject * value ) {
auto list = self - > data . get ( ) ;
if ( ! list ) {
PyErr_SetString ( PyExc_RuntimeError , " the collection store returned a null pointer " ) ;
return NULL ;
}
// Type checking - must be an Entity
if ( ! PyObject_IsInstance ( value , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
// Not an Entity, so count is 0
return PyLong_FromLong ( 0 ) ;
}
// Get the C++ object from the Python object
PyUIEntityObject * entity = ( PyUIEntityObject * ) value ;
if ( ! entity - > data ) {
return PyLong_FromLong ( 0 ) ;
}
// Count occurrences
Py_ssize_t count = 0 ;
for ( const auto & ent : * list ) {
if ( ent . get ( ) = = entity - > data . get ( ) ) {
count + + ;
}
}
return PyLong_FromSsize_t ( count ) ;
}
PyObject * UIEntityCollection : : subscript ( PyUIEntityCollectionObject * self , PyObject * key ) {
if ( PyLong_Check ( key ) ) {
// Single index - delegate to sq_item
Py_ssize_t index = PyLong_AsSsize_t ( key ) ;
if ( index = = - 1 & & PyErr_Occurred ( ) ) {
return NULL ;
}
return getitem ( self , index ) ;
} else if ( PySlice_Check ( key ) ) {
// Handle slice
Py_ssize_t start , stop , step , slicelength ;
if ( PySlice_GetIndicesEx ( key , self - > data - > size ( ) , & start , & stop , & step , & slicelength ) < 0 ) {
return NULL ;
}
PyObject * result_list = PyList_New ( slicelength ) ;
if ( ! result_list ) {
return NULL ;
}
// Iterate through the list with slice parameters
auto it = self - > data - > begin ( ) ;
for ( Py_ssize_t i = 0 , cur = start ; i < slicelength ; i + + , cur + = step ) {
auto cur_it = it ;
std : : advance ( cur_it , cur ) ;
auto type = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ;
auto obj = ( PyUIEntityObject * ) type - > tp_alloc ( type , 0 ) ;
if ( obj ) {
obj - > data = * cur_it ;
PyList_SET_ITEM ( result_list , i , ( PyObject * ) obj ) ; // Steals reference
} else {
Py_DECREF ( result_list ) ;
Py_DECREF ( type ) ;
return NULL ;
}
Py_DECREF ( type ) ;
}
return result_list ;
} else {
PyErr_Format ( PyExc_TypeError , " EntityCollection indices must be integers or slices, not %.200s " ,
Py_TYPE ( key ) - > tp_name ) ;
return NULL ;
}
}
int UIEntityCollection : : ass_subscript ( PyUIEntityCollectionObject * self , PyObject * key , PyObject * value ) {
if ( PyLong_Check ( key ) ) {
// Single index - delegate to sq_ass_item
Py_ssize_t index = PyLong_AsSsize_t ( key ) ;
if ( index = = - 1 & & PyErr_Occurred ( ) ) {
return - 1 ;
}
return setitem ( self , index , value ) ;
} else if ( PySlice_Check ( key ) ) {
// Handle slice assignment/deletion
Py_ssize_t start , stop , step , slicelength ;
if ( PySlice_GetIndicesEx ( key , self - > data - > size ( ) , & start , & stop , & step , & slicelength ) < 0 ) {
return - 1 ;
}
if ( value = = NULL ) {
// Deletion
if ( step ! = 1 ) {
// For non-contiguous slices, delete from highest to lowest to maintain indices
std : : vector < Py_ssize_t > indices ;
for ( Py_ssize_t i = 0 , cur = start ; i < slicelength ; i + + , cur + = step ) {
indices . push_back ( cur ) ;
}
// Sort in descending order
std : : sort ( indices . begin ( ) , indices . end ( ) , std : : greater < Py_ssize_t > ( ) ) ;
// Delete each index
for ( Py_ssize_t idx : indices ) {
auto it = self - > data - > begin ( ) ;
std : : advance ( it , idx ) ;
( * it ) - > grid = nullptr ; // Clear grid reference
self - > data - > erase ( it ) ;
}
} else {
// Contiguous slice - delete range
auto it_start = self - > data - > begin ( ) ;
auto it_stop = self - > data - > begin ( ) ;
std : : advance ( it_start , start ) ;
std : : advance ( it_stop , stop ) ;
// Clear grid references
for ( auto it = it_start ; it ! = it_stop ; + + it ) {
( * it ) - > grid = nullptr ;
}
self - > data - > erase ( it_start , it_stop ) ;
}
return 0 ;
} else {
// Assignment
if ( ! PySequence_Check ( value ) ) {
PyErr_SetString ( PyExc_TypeError , " can only assign sequence to slice " ) ;
return - 1 ;
}
Py_ssize_t value_len = PySequence_Length ( value ) ;
if ( value_len = = - 1 ) {
return - 1 ;
}
// Validate all items first
std : : vector < std : : shared_ptr < UIEntity > > new_items ;
for ( Py_ssize_t i = 0 ; i < value_len ; i + + ) {
PyObject * item = PySequence_GetItem ( value , i ) ;
if ( ! item ) {
return - 1 ;
}
// Type check
if ( ! PyObject_IsInstance ( item , PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " Entity " ) ) ) {
Py_DECREF ( item ) ;
PyErr_Format ( PyExc_TypeError ,
" EntityCollection can only contain Entity objects; "
" got %s at index %zd " , Py_TYPE ( item ) - > tp_name , i ) ;
return - 1 ;
}
PyUIEntityObject * entity = ( PyUIEntityObject * ) item ;
Py_DECREF ( item ) ;
new_items . push_back ( entity - > data ) ;
}
// Now perform the assignment
if ( step = = 1 ) {
// Contiguous slice
if ( slicelength ! = value_len ) {
// Need to resize - remove old items and insert new ones
auto it_start = self - > data - > begin ( ) ;
auto it_stop = self - > data - > begin ( ) ;
std : : advance ( it_start , start ) ;
std : : advance ( it_stop , stop ) ;
// Clear grid references from old items
for ( auto it = it_start ; it ! = it_stop ; + + it ) {
( * it ) - > grid = nullptr ;
}
// Erase old range
it_start = self - > data - > erase ( it_start , it_stop ) ;
// Insert new items
for ( const auto & entity : new_items ) {
entity - > grid = self - > grid ;
it_start = self - > data - > insert ( it_start , entity ) ;
+ + it_start ;
}
} else {
// Same size, just replace
auto it = self - > data - > begin ( ) ;
std : : advance ( it , start ) ;
for ( const auto & entity : new_items ) {
( * it ) - > grid = nullptr ; // Clear old grid ref
* it = entity ;
entity - > grid = self - > grid ; // Set new grid ref
+ + it ;
}
}
} else {
// Extended slice
if ( slicelength ! = value_len ) {
PyErr_Format ( PyExc_ValueError ,
" attempt to assign sequence of size %zd to extended slice of size %zd " ,
value_len , slicelength ) ;
return - 1 ;
}
auto list_it = self - > data - > begin ( ) ;
for ( Py_ssize_t i = 0 , cur = start ; i < slicelength ; i + + , cur + = step ) {
auto cur_it = list_it ;
std : : advance ( cur_it , cur ) ;
( * cur_it ) - > grid = nullptr ; // Clear old grid ref
* cur_it = new_items [ i ] ;
new_items [ i ] - > grid = self - > grid ; // Set new grid ref
}
}
return 0 ;
}
} else {
PyErr_Format ( PyExc_TypeError , " EntityCollection indices must be integers or slices, not %.200s " ,
Py_TYPE ( key ) - > tp_name ) ;
return - 1 ;
}
}
PyMappingMethods UIEntityCollection : : mpmethods = {
. mp_length = ( lenfunc ) UIEntityCollection : : len ,
. mp_subscript = ( binaryfunc ) UIEntityCollection : : subscript ,
. mp_ass_subscript = ( objobjargproc ) UIEntityCollection : : ass_subscript
} ;
2024-04-20 10:32:04 -04:00
PyMethodDef UIEntityCollection : : methods [ ] = {
{ " append " , ( PyCFunction ) UIEntityCollection : : append , METH_O } ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
{ " extend " , ( PyCFunction ) UIEntityCollection : : extend , METH_O } ,
2024-04-20 10:32:04 -04:00
{ " remove " , ( PyCFunction ) UIEntityCollection : : remove , METH_O } ,
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
{ " index " , ( PyCFunction ) UIEntityCollection : : index_method , METH_O } ,
{ " count " , ( PyCFunction ) UIEntityCollection : : count , METH_O } ,
2024-04-20 10:32:04 -04:00
{ NULL , NULL , 0 , NULL }
} ;
PyObject * UIEntityCollection : : repr ( PyUIEntityCollectionObject * self )
{
std : : ostringstream ss ;
if ( ! self - > data ) ss < < " <UICollection (invalid internal object)> " ;
else {
ss < < " <UICollection ( " < < self - > data - > size ( ) < < " child objects)> " ;
}
std : : string repr_str = ss . str ( ) ;
return PyUnicode_DecodeUTF8 ( repr_str . c_str ( ) , repr_str . size ( ) , " replace " ) ;
}
int UIEntityCollection : : init ( PyUIEntityCollectionObject * self , PyObject * args , PyObject * kwds )
{
PyErr_SetString ( PyExc_TypeError , " EntityCollection cannot be instantiated: a C++ data source is required. " ) ;
return - 1 ;
}
PyObject * UIEntityCollection : : iter ( PyUIEntityCollectionObject * self )
{
Iterators, other Python C API improvements
closes #72
ref #69 - this resolves the "UICollection" (not "UIEntityCollection", perhaps renamed since the issue opened) and "UIEntityCollection" portion. The Grid point based iterators were not updated.
**RPATH updates**
Will this RPATH setting allow McRogueFace to execute using its included "lib" subdirectory after being unzipped on a new computer?
The change from "./lib" to "$ORIGIN/./lib" improves portability. The $ORIGIN token is a special Linux/Unix convention that refers to the directory containing the executable itself. This makes the path relative to the executable's location rather than the current working directory, which means McRogueFace will correctly find its libraries in the lib subdirectory regardless of where it's run from after being unzipped on a new computer.
**New standard object initialization**
PyColor, PyVector
- Fixed all 15 PyTypeObject definitions to use proper designated initializer syntax
- Replaced PyType_GenericAlloc usage in PyColor.cpp and PyVector.cpp
- Updated PyObject_New usage in UIEntity.cpp
- All object creation now uses module-based type lookups instead of static references
- Created centralized utilities in PyObjectUtils.h
**RAII Wrappers**
automatic reference counting via C++ object lifecycle
- Created PyRAII.h with PyObjectRef and PyTypeRef classes
- These provide automatic reference counting management
- Updated PyColor::from_arg() to demonstrate RAII usage
- Prevents memory leaks and reference counting errors
**Python object base in type defs:**
`.ob_base = {.ob_base = {.ob_refcnt = 1, .ob_type = NULL}, .ob_size = 0}`
PyColor, PyTexture, PyVector, UICaption, UICollection, UIEntity, UIFrame, UIGrid
**convertDrawableToPython**
replace crazy macro to detect the correct Python type of a UIDrawable instance
- Removed the problematic macro from UIDrawable.h
- Created template-based functions in PyObjectUtils.h
- Updated UICollection.cpp to use local helper function
- The new approach is cleaner, more debuggable, and avoids static type references
**Iterator fixes**
tp_iter on UICollection, UIGrid, UIGridPoint, UISprite
UIGrid logic improved, standard
**List vs Vector usage analysis**
there are different use cases that weren't standardized:
- UICollection (for Frame children) uses std::vector<std::shared_ptr<UIDrawable>>
- UIEntityCollection (for Grid entities) uses std::list<std::shared_ptr<UIEntity>>
The rationale is currently connected to frequency of expected changes.
* A "UICollection" is likely either all visible or not; it's also likely to be created once and have a static set of contents. They should be contiguous in memory in hopes that this helps rendering speed.
* A "UIEntityCollection" is expected to be rendered as a subset within the visible rectangle of the UIGrid. Scrolling the grid or gameplay logic is likely to frequently create and destroy entities. In general I expect Entity collections to have a much higher common size than UICollections. For these reasons I've made them Lists in hopes that they never have to be reallocated or moved during a frame.
2025-05-31 08:58:52 -04:00
// Get the iterator type from the module to ensure we have the registered version
PyTypeObject * iterType = ( PyTypeObject * ) PyObject_GetAttrString ( McRFPy_API : : mcrf_module , " UIEntityCollectionIter " ) ;
if ( ! iterType ) {
PyErr_SetString ( PyExc_RuntimeError , " Could not find UIEntityCollectionIter type in module " ) ;
return NULL ;
}
// Allocate new iterator instance
PyUIEntityCollectionIterObject * iterObj = ( PyUIEntityCollectionIterObject * ) iterType - > tp_alloc ( iterType , 0 ) ;
2024-04-20 10:32:04 -04:00
if ( iterObj = = NULL ) {
Iterators, other Python C API improvements
closes #72
ref #69 - this resolves the "UICollection" (not "UIEntityCollection", perhaps renamed since the issue opened) and "UIEntityCollection" portion. The Grid point based iterators were not updated.
**RPATH updates**
Will this RPATH setting allow McRogueFace to execute using its included "lib" subdirectory after being unzipped on a new computer?
The change from "./lib" to "$ORIGIN/./lib" improves portability. The $ORIGIN token is a special Linux/Unix convention that refers to the directory containing the executable itself. This makes the path relative to the executable's location rather than the current working directory, which means McRogueFace will correctly find its libraries in the lib subdirectory regardless of where it's run from after being unzipped on a new computer.
**New standard object initialization**
PyColor, PyVector
- Fixed all 15 PyTypeObject definitions to use proper designated initializer syntax
- Replaced PyType_GenericAlloc usage in PyColor.cpp and PyVector.cpp
- Updated PyObject_New usage in UIEntity.cpp
- All object creation now uses module-based type lookups instead of static references
- Created centralized utilities in PyObjectUtils.h
**RAII Wrappers**
automatic reference counting via C++ object lifecycle
- Created PyRAII.h with PyObjectRef and PyTypeRef classes
- These provide automatic reference counting management
- Updated PyColor::from_arg() to demonstrate RAII usage
- Prevents memory leaks and reference counting errors
**Python object base in type defs:**
`.ob_base = {.ob_base = {.ob_refcnt = 1, .ob_type = NULL}, .ob_size = 0}`
PyColor, PyTexture, PyVector, UICaption, UICollection, UIEntity, UIFrame, UIGrid
**convertDrawableToPython**
replace crazy macro to detect the correct Python type of a UIDrawable instance
- Removed the problematic macro from UIDrawable.h
- Created template-based functions in PyObjectUtils.h
- Updated UICollection.cpp to use local helper function
- The new approach is cleaner, more debuggable, and avoids static type references
**Iterator fixes**
tp_iter on UICollection, UIGrid, UIGridPoint, UISprite
UIGrid logic improved, standard
**List vs Vector usage analysis**
there are different use cases that weren't standardized:
- UICollection (for Frame children) uses std::vector<std::shared_ptr<UIDrawable>>
- UIEntityCollection (for Grid entities) uses std::list<std::shared_ptr<UIEntity>>
The rationale is currently connected to frequency of expected changes.
* A "UICollection" is likely either all visible or not; it's also likely to be created once and have a static set of contents. They should be contiguous in memory in hopes that this helps rendering speed.
* A "UIEntityCollection" is expected to be rendered as a subset within the visible rectangle of the UIGrid. Scrolling the grid or gameplay logic is likely to frequently create and destroy entities. In general I expect Entity collections to have a much higher common size than UICollections. For these reasons I've made them Lists in hopes that they never have to be reallocated or moved during a frame.
2025-05-31 08:58:52 -04:00
Py_DECREF ( iterType ) ;
2024-04-20 10:32:04 -04:00
return NULL ; // Failed to allocate memory for the iterator object
}
iterObj - > data = self - > data ;
iterObj - > index = 0 ;
iterObj - > start_size = self - > data - > size ( ) ;
Iterators, other Python C API improvements
closes #72
ref #69 - this resolves the "UICollection" (not "UIEntityCollection", perhaps renamed since the issue opened) and "UIEntityCollection" portion. The Grid point based iterators were not updated.
**RPATH updates**
Will this RPATH setting allow McRogueFace to execute using its included "lib" subdirectory after being unzipped on a new computer?
The change from "./lib" to "$ORIGIN/./lib" improves portability. The $ORIGIN token is a special Linux/Unix convention that refers to the directory containing the executable itself. This makes the path relative to the executable's location rather than the current working directory, which means McRogueFace will correctly find its libraries in the lib subdirectory regardless of where it's run from after being unzipped on a new computer.
**New standard object initialization**
PyColor, PyVector
- Fixed all 15 PyTypeObject definitions to use proper designated initializer syntax
- Replaced PyType_GenericAlloc usage in PyColor.cpp and PyVector.cpp
- Updated PyObject_New usage in UIEntity.cpp
- All object creation now uses module-based type lookups instead of static references
- Created centralized utilities in PyObjectUtils.h
**RAII Wrappers**
automatic reference counting via C++ object lifecycle
- Created PyRAII.h with PyObjectRef and PyTypeRef classes
- These provide automatic reference counting management
- Updated PyColor::from_arg() to demonstrate RAII usage
- Prevents memory leaks and reference counting errors
**Python object base in type defs:**
`.ob_base = {.ob_base = {.ob_refcnt = 1, .ob_type = NULL}, .ob_size = 0}`
PyColor, PyTexture, PyVector, UICaption, UICollection, UIEntity, UIFrame, UIGrid
**convertDrawableToPython**
replace crazy macro to detect the correct Python type of a UIDrawable instance
- Removed the problematic macro from UIDrawable.h
- Created template-based functions in PyObjectUtils.h
- Updated UICollection.cpp to use local helper function
- The new approach is cleaner, more debuggable, and avoids static type references
**Iterator fixes**
tp_iter on UICollection, UIGrid, UIGridPoint, UISprite
UIGrid logic improved, standard
**List vs Vector usage analysis**
there are different use cases that weren't standardized:
- UICollection (for Frame children) uses std::vector<std::shared_ptr<UIDrawable>>
- UIEntityCollection (for Grid entities) uses std::list<std::shared_ptr<UIEntity>>
The rationale is currently connected to frequency of expected changes.
* A "UICollection" is likely either all visible or not; it's also likely to be created once and have a static set of contents. They should be contiguous in memory in hopes that this helps rendering speed.
* A "UIEntityCollection" is expected to be rendered as a subset within the visible rectangle of the UIGrid. Scrolling the grid or gameplay logic is likely to frequently create and destroy entities. In general I expect Entity collections to have a much higher common size than UICollections. For these reasons I've made them Lists in hopes that they never have to be reallocated or moved during a frame.
2025-05-31 08:58:52 -04:00
Py_DECREF ( iterType ) ;
2024-04-20 10:32:04 -04:00
return ( PyObject * ) iterObj ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
// Property system implementation for animations
bool UIGrid : : setProperty ( const std : : string & name , float value ) {
if ( name = = " x " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
position . x = value ;
box . setPosition ( position ) ;
output . setPosition ( position ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " y " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
position . y = value ;
box . setPosition ( position ) ;
output . setPosition ( position ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " w " | | name = = " width " ) {
box . setSize ( sf : : Vector2f ( value , box . getSize ( ) . y ) ) ;
output . setTextureRect ( sf : : IntRect ( 0 , 0 , box . getSize ( ) . x , box . getSize ( ) . y ) ) ;
return true ;
}
else if ( name = = " h " | | name = = " height " ) {
box . setSize ( sf : : Vector2f ( box . getSize ( ) . x , value ) ) ;
output . setTextureRect ( sf : : IntRect ( 0 , 0 , box . getSize ( ) . x , box . getSize ( ) . y ) ) ;
return true ;
}
else if ( name = = " center_x " ) {
center_x = value ;
return true ;
}
else if ( name = = " center_y " ) {
center_y = value ;
return true ;
}
else if ( name = = " zoom " ) {
zoom = value ;
return true ;
}
else if ( name = = " z_index " ) {
z_index = static_cast < int > ( value ) ;
return true ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
else if ( name = = " fill_color.r " ) {
fill_color . r = static_cast < uint8_t > ( std : : max ( 0.0f , std : : min ( 255.0f , value ) ) ) ;
return true ;
}
else if ( name = = " fill_color.g " ) {
fill_color . g = static_cast < uint8_t > ( std : : max ( 0.0f , std : : min ( 255.0f , value ) ) ) ;
return true ;
}
else if ( name = = " fill_color.b " ) {
fill_color . b = static_cast < uint8_t > ( std : : max ( 0.0f , std : : min ( 255.0f , value ) ) ) ;
return true ;
}
else if ( name = = " fill_color.a " ) {
fill_color . a = static_cast < uint8_t > ( std : : max ( 0.0f , std : : min ( 255.0f , value ) ) ) ;
return true ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return false ;
}
bool UIGrid : : setProperty ( const std : : string & name , const sf : : Vector2f & value ) {
if ( name = = " position " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
position = value ;
box . setPosition ( position ) ;
output . setPosition ( position ) ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " size " ) {
box . setSize ( value ) ;
output . setTextureRect ( sf : : IntRect ( 0 , 0 , box . getSize ( ) . x , box . getSize ( ) . y ) ) ;
return true ;
}
else if ( name = = " center " ) {
center_x = value . x ;
center_y = value . y ;
return true ;
}
return false ;
}
bool UIGrid : : getProperty ( const std : : string & name , float & value ) const {
if ( name = = " x " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
value = position . x ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " y " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
value = position . y ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " w " | | name = = " width " ) {
value = box . getSize ( ) . x ;
return true ;
}
else if ( name = = " h " | | name = = " height " ) {
value = box . getSize ( ) . y ;
return true ;
}
else if ( name = = " center_x " ) {
value = center_x ;
return true ;
}
else if ( name = = " center_y " ) {
value = center_y ;
return true ;
}
else if ( name = = " zoom " ) {
value = zoom ;
return true ;
}
else if ( name = = " z_index " ) {
value = static_cast < float > ( z_index ) ;
return true ;
}
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
else if ( name = = " fill_color.r " ) {
value = static_cast < float > ( fill_color . r ) ;
return true ;
}
else if ( name = = " fill_color.g " ) {
value = static_cast < float > ( fill_color . g ) ;
return true ;
}
else if ( name = = " fill_color.b " ) {
value = static_cast < float > ( fill_color . b ) ;
return true ;
}
else if ( name = = " fill_color.a " ) {
value = static_cast < float > ( fill_color . a ) ;
return true ;
}
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return false ;
}
bool UIGrid : : getProperty ( const std : : string & name , sf : : Vector2f & value ) const {
if ( name = = " position " ) {
Squashed commit of 53 Commits: [alpha_streamline_2]
* Field of View, Pathing courtesy of libtcod
* python-tcod emulation at `mcrfpy.libtcod` - partial implementation
* documentation, tutorial drafts: in middling to good shape
┌────────────┬────────────────────┬───────────┬────────────┬───────────────┬────────────────┬────────────────┬─────────────┐
│ Date │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-05 │ - opus-4 │ 13,630 │ 159,500 │ 3,854,900 │ 84,185,034 │ 88,213,064 │ $210.72 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-06 │ - opus-4 │ 5,814 │ 113,190 │ 4,242,407 │ 150,191,183 │ 154,552,594 │ $313.41 │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-07 │ - opus-4 │ 7,244 │ 104,599 │ 3,894,453 │ 81,781,179 │ 85,787,475 │ $184.46 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-08 │ - opus-4 │ 50,312 │ 158,599 │ 5,021,189 │ 60,028,561 │ 65,258,661 │ $167.05 │
│ │ - sonnet-4 │ │ │ │ │ │ │
├────────────┼────────────────────┼───────────┼────────────┼───────────────┼────────────────┼────────────────┼─────────────┤
│ 2025-07-09 │ - opus-4 │ 6,311 │ 109,653 │ 4,171,140 │ 80,092,875 │ 84,379,979 │ $193.09 │
│ │ - sonnet-4 │ │ │ │ │ │ │
└────────────┴────────────────────┴───────────┴────────────┴───────────────┴────────────────┴────────────────┴─────────────┘
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Author: John McCardle <mccardle.john@gmail.com>
Draft tutorials
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with FOV, A* pathfinding, and GUI text widget completions
- Mark TCOD Integration Sprint as complete
- Document FOV system with perspective rendering implementation
- Update UIEntity pathfinding status to complete with A* and caching
- Add comprehensive achievement entry for July 10 work
- Reflect current engine capabilities accurately
The engine now has all core roguelike mechanics:
- Field of View with per-entity visibility
- Pathfinding (both Dijkstra and A*)
- Text input for in-game consoles
- Performance optimizations throughout
Author: John McCardle <mccardle.john@gmail.com>
feat(engine): implement perspective FOV, pathfinding, and GUI text widgets
Major Engine Enhancements:
- Complete FOV (Field of View) system with perspective rendering
- UIGrid.perspective property for entity-based visibility
- Three-layer overlay colors (unexplored, explored, visible)
- Per-entity visibility state tracking
- Perfect knowledge updates only for explored areas
- Advanced Pathfinding Integration
- A* pathfinding implementation in UIGrid
- Entity.path_to() method for direct pathfinding
- Dijkstra maps for multi-target pathfinding
- Path caching for performance optimization
- GUI Text Input Widgets
- TextInputWidget class with cursor, selection, scrolling
- Improved widget with proper text rendering and input handling
- Example showcase of multiple text input fields
- Foundation for in-game console and chat systems
- Performance & Architecture Improvements
- PyTexture copy operations optimized
- GameEngine update cycle refined
- UIEntity property handling enhanced
- UITestScene modernized
Test Suite:
- Interactive visibility demos showing FOV in action
- Pathfinding comparison (A* vs Dijkstra)
- Debug utilities for visibility and empty path handling
- Sizzle reel demo combining pathfinding and vision
- Multiple text input test scenarios
This commit brings McRogueFace closer to a complete roguelike engine
with essential features like line-of-sight, intelligent pathfinding,
and interactive text input capabilities.
Author: John McCardle <mccardle.john@gmail.com>
feat(demos): enhance interactive pathfinding demos with entity.path_to()
- dijkstra_interactive_enhanced.py: Animation along paths with smooth movement
- M key to start movement animation
- P to pause/resume
- R to reset positions
- Visual path gradient for better clarity
- pathfinding_showcase.py: Advanced multi-entity behaviors
- Chase mode: enemies pursue player
- Flee mode: enemies avoid player
- Patrol mode: entities follow waypoints
- WASD player movement
- Dijkstra distance field visualization (D key)
- Larger dungeon map with multiple rooms
- Both demos use new entity.path_to() method
- Smooth interpolated movement animations
- Real-time pathfinding recalculation
- Comprehensive test coverage
These demos showcase the power of integrated pathfinding for game AI.
Author: John McCardle <mccardle.john@gmail.com>
feat(entity): implement path_to() method for entity pathfinding
- Add path_to(target_x, target_y) method to UIEntity class
- Uses existing Dijkstra pathfinding implementation from UIGrid
- Returns list of (x, y) coordinate tuples for complete path
- Supports both positional and keyword argument formats
- Proper error handling for out-of-bounds and no-grid scenarios
- Comprehensive test suite covering normal and edge cases
Part of TCOD integration sprint - gives entities immediate pathfinding capabilities.
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap with Dijkstra pathfinding progress
- Mark UIGrid TCOD Integration as completed
- Document critical PyArg bug fix achievement
- Update UIEntity Pathfinding to 50% complete
- Add detailed progress notes for July 9 sprint work
Author: John McCardle <mccardle.john@gmail.com>
feat(tcod): complete Dijkstra pathfinding implementation with critical PyArg fix
- Add complete Dijkstra pathfinding to UIGrid class
- compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path()
- Full TCODMap and TCODDijkstra integration
- Proper memory management in constructors/destructors
- Create mcrfpy.libtcod submodule with Python bindings
- dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path()
- line() function for drawing corridors
- Foundation for future FOV and pathfinding algorithms
- Fix critical PyArg bug in UIGridPoint color setter
- PyObject_to_sfColor() now handles both Color objects and tuples
- Prevents "SystemError: new style getargs format but argument is not a tuple"
- Proper error handling and exception propagation
- Add comprehensive test suite
- test_dijkstra_simple.py validates all pathfinding operations
- dijkstra_test.py for headless testing with screenshots
- dijkstra_interactive.py for full user interaction demos
- Consolidate and clean up test files
- Removed 6 duplicate/broken demo attempts
- Two clean versions: headless test + interactive demo
Part of TCOD integration sprint for RoguelikeDev Tutorial Event.
Author: John McCardle <mccardle.john@gmail.com>
Roguelike Tutorial Planning + Prep
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete markdown API documentation export
- Created comprehensive markdown documentation matching HTML completeness
- Documented all 75 functions, 20 classes, 56 methods, and 20 automation methods
- Zero ellipsis instances - complete coverage with no missing documentation
- Added proper markdown formatting with code blocks and navigation
- Included full parameter documentation, return values, and examples
Key features:
- 23KB GitHub-compatible markdown documentation
- 47 argument sections with detailed parameters
- 35 return value specifications
- 23 code examples with syntax highlighting
- 38 explanatory notes and 10 exception specifications
- Full table of contents with anchor links
- Professional markdown formatting
Both export formats now available:
- HTML: docs/api_reference_complete.html (54KB, rich styling)
- Markdown: docs/API_REFERENCE_COMPLETE.md (23KB, GitHub-compatible)
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): complete API documentation with zero missing methods
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions
Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation
Author: John McCardle <mccardle.john@gmail.com>
feat(docs): create professional HTML API documentation
- Fixed all formatting issues from original HTML output
- Added comprehensive constructor documentation for all classes
- Enhanced visual design with modern styling and typography
- Fixed literal newline display and markdown link conversion
- Added proper semantic HTML structure and navigation
- Includes detailed documentation for Entity, collections, and system types
Author: John McCardle <mccardle.john@gmail.com>
feat: complete API reference generator and finish Phase 7 documentation
Implemented comprehensive API documentation generator that:
- Introspects live mcrfpy module for accurate documentation
- Generates organized Markdown reference (docs/API_REFERENCE.md)
- Categorizes classes and functions by type
- Includes full automation module documentation
- Provides summary statistics
Results:
- 20 classes documented
- 19 module functions documented
- 20 automation methods documented
- 100% coverage of public API
- Clean, readable Markdown output
Phase 7 Summary:
- Completed 4/5 tasks (1 cancelled as architecturally inappropriate)
- All documentation tasks successful
- Type stubs, docstrings, and API reference all complete
Author: John McCardle <mccardle.john@gmail.com>
docs: cancel PyPI wheel task and add future vision for Python extension architecture
Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python
Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)
Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility
This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.
Author: John McCardle <mccardle.john@gmail.com>
feat: generate comprehensive .pyi type stubs for IDE support (#108)
Created complete type stub files for the mcrfpy module to enable:
- Full IntelliSense/autocomplete in IDEs
- Static type checking with mypy/pyright
- Better documentation tooltips
- Parameter hints and return types
Implementation details:
- Manually crafted stubs for accuracy (15KB, 533 lines)
- Complete coverage: 19 classes, 112 functions/methods
- Proper type annotations using typing module
- @overload decorators for multiple signatures
- Type aliases for common patterns (UIElement union)
- Preserved all docstrings for IDE help
- Automation module fully typed
- PEP 561 compliant with py.typed marker
Testing:
- Validated Python syntax with ast.parse()
- Verified all expected classes and functions
- Confirmed type annotations are well-formed
- Checked docstring preservation (80 docstrings)
Usage:
- VS Code: Add stubs/ to python.analysis.extraPaths
- PyCharm: Mark stubs/ directory as Sources Root
- Other IDEs will auto-detect .pyi files
This significantly improves the developer experience when using
McRogueFace as a Python game engine.
Author: John McCardle <mccardle.john@gmail.com>
docs: add comprehensive parameter documentation to all API methods (#86)
Enhanced documentation for the mcrfpy module with:
- Detailed docstrings for all API methods
- Type hints in documentation (name: type format)
- Return type specifications
- Exception documentation where applicable
- Usage examples for complex methods
- Module-level documentation with overview and example code
Specific improvements:
- Audio API: Added parameter types and return values
- Scene API: Documented transition types and error conditions
- Timer API: Clarified handler signature and runtime parameter
- UI Search: Added wildcard pattern examples for findAll()
- Metrics API: Documented all dictionary keys returned
Also fixed method signatures:
- Changed METH_VARARGS to METH_NOARGS for parameterless methods
- Ensures proper Python calling conventions
Test coverage included - all documentation is accessible via Python's
__doc__ attributes and shows correctly formatted information.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark issue #85 as completed in Phase 7
Author: John McCardle <mccardle.john@gmail.com>
docs: replace all 'docstring' placeholders with comprehensive documentation (#85)
Added proper Python docstrings for all UI component classes:
UIFrame:
- Container element that can hold child drawables
- Documents position, size, colors, outline, and clip_children
- Includes constructor signature with all parameters
UICaption:
- Text display element with font and styling
- Documents text content, position, font, colors, outline
- Notes that w/h are computed from text content
UISprite:
- Texture/sprite display element
- Documents position, texture, sprite_index, scale
- Notes that w/h are computed from texture and scale
UIGrid:
- Tile-based grid for game worlds
- Documents grid dimensions, tile size, texture atlas
- Includes entities collection and background_color
All docstrings follow consistent format:
- Constructor signature with defaults
- Brief description
- Args section with types and defaults
- Attributes section with all properties
This completes Phase 7 task #85 for documentation improvements.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP with PyArgHelpers infrastructure completion
Author: John McCardle <mccardle.john@gmail.com>
refactor: implement PyArgHelpers for standardized Python argument parsing
This major refactoring standardizes how position, size, and other arguments
are parsed across all UI components. PyArgHelpers provides consistent handling
for various argument patterns:
- Position as (x, y) tuple or separate x, y args
- Size as (w, h) tuple or separate width, height args
- Grid position and size with proper validation
- Color parsing with PyColorObject support
Changes across UI components:
- UICaption: Migrated to PyArgHelpers, improved resize() for future multiline support
- UIFrame: Uses standardized position parsing
- UISprite: Consistent position handling
- UIGrid: Grid-specific position/size helpers
- UIEntity: Unified argument parsing
Also includes:
- Improved error messages for type mismatches (int or float accepted)
- Reduced code duplication across constructors
- Better handling of keyword/positional argument conflicts
- Maintains backward compatibility with existing API
This addresses the inconsistent argument handling patterns discovered during
the inheritance hierarchy work and prepares for Phase 7 documentation.
Author: John McCardle <mccardle.john@gmail.com>
feat(Python): establish proper inheritance hierarchy for UI types
All UIDrawable-derived Python types now properly inherit from the Drawable
base class in Python, matching the C++ inheritance structure.
Changes:
- Add Py_TPFLAGS_BASETYPE to PyDrawableType to allow inheritance
- Set tp_base = &mcrfpydef::PyDrawableType for all UI types
- Add PyDrawable.h include to UI type headers
- Rename _Drawable to Drawable and update error message
This enables proper Python inheritance: Frame, Caption, Sprite, Grid,
and Entity all inherit from Drawable, allowing shared functionality
and isinstance() checks.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UISprite)
- Update UISprite to use base class position instead of sprite position
- Synchronize sprite position with base class position for rendering
- Implement onPositionChanged() for position synchronization
- Update all UISprite methods to use base position consistently
- Add comprehensive test coverage for UISprite position handling
This is part 3 of moving position to the base class. UIGrid is the final
class that needs to be updated.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UICaption)
- Update UICaption to use base class position instead of text position
- Synchronize text position with base class position for rendering
- Add onPositionChanged() virtual method for position synchronization
- Update all UICaption methods to use base position consistently
- Add comprehensive test coverage for UICaption position handling
This is part 2 of moving position to the base class. UISprite and UIGrid
will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: move position property to UIDrawable base class (UIFrame)
- Add position member to UIDrawable base class
- Add common position getters/setters (x, y, pos) to base class
- Update UIFrame to use base class position instead of box position
- Synchronize box position with base class position for rendering
- Update all UIFrame methods to use base position consistently
- Add comprehensive test coverage for UIFrame position handling
This is part 1 of moving position to the base class. Other derived classes
(UICaption, UISprite, UIGrid) will be updated in subsequent commits.
Author: John McCardle <mccardle.john@gmail.com>
refactor: remove UIEntity collision_pos field
- Remove redundant collision_pos field from UIEntity
- Update position getters/setters to use integer-cast position when needed
- Remove all collision_pos synchronization code
- Simplify entity position handling to use single float position field
- Add comprehensive test coverage proving functionality is preserved
This removes technical debt and simplifies the codebase without changing API behavior.
Author: John McCardle <mccardle.john@gmail.com>
feat: add PyArgHelpers infrastructure for standardized argument parsing
- Create PyArgHelpers.h with parsing functions for position, size, grid coordinates, and color
- Support tuple-based vector arguments with conflict detection
- Provide consistent error messages and validation
- Add comprehensive test coverage for infrastructure
This sets the foundation for standardizing all Python API constructors.
Author: John McCardle <mccardle.john@gmail.com>
docs: mark Phase 6 (Rendering Revolution) as complete
Phase 6 is now complete with all core rendering features implemented:
Completed Features:
- Grid background colors (#50) - customizable backgrounds with animation
- RenderTexture overhaul (#6) - UIFrame clipping with opt-in architecture
- Viewport-based rendering (#8) - three scaling modes with coordinate transform
Strategic Decisions:
- UIGrid already has optimal RenderTexture implementation for its viewport needs
- UICaption/UISprite clipping deemed unnecessary (no children to clip)
- Effects/Shader/Particle systems deferred to post-Phase 7 for focused delivery
The rendering foundation is now solid and ready for Phase 7: Documentation & Distribution.
Author: John McCardle <mccardle.john@gmail.com>
feat(viewport): complete viewport-based rendering system (#8)
Implements a comprehensive viewport system that allows fixed game resolution
with flexible window scaling, addressing the primary wishes for issues #34, #49, and #8.
Key Features:
- Fixed game resolution independent of window size (window.game_resolution property)
- Three scaling modes accessible via window.scaling_mode:
- "center": 1:1 pixels, viewport centered in window
- "stretch": viewport fills window, ignores aspect ratio
- "fit": maintains aspect ratio with black bars
- Automatic window-to-game coordinate transformation for mouse input
- Full Python API integration with PyWindow properties
Technical Implementation:
- GameEngine::ViewportMode enum with Center, Stretch, Fit modes
- SFML View system for efficient GPU-based viewport scaling
- updateViewport() recalculates on window resize or mode change
- windowToGameCoords() transforms mouse coordinates correctly
- PyScene mouse input automatically uses transformed coordinates
Tests:
- test_viewport_simple.py: Basic API functionality
- test_viewport_visual.py: Visual verification with screenshots
- test_viewport_scaling.py: Interactive mode switching and resizing
This completes the viewport-based rendering task and provides the foundation
for resolution-independent game development as requested for Crypt of Sokoban.
Author: John McCardle <mccardle.john@gmail.com>
docs: update ROADMAP for Phase 6 progress
- Marked Phase 6 as IN PROGRESS
- Updated RenderTexture overhaul (#6) as PARTIALLY COMPLETE
- Marked Grid background colors (#50) as COMPLETED
- Added technical notes from implementation experience
- Identified viewport rendering (#8) as next priority
Author: John McCardle <mccardle.john@gmail.com>
feat(rendering): implement RenderTexture base infrastructure and UIFrame clipping (#6)
- Added RenderTexture support to UIDrawable base class
- std::unique_ptr<sf::RenderTexture> for opt-in rendering
- Dirty flag system for optimization
- enableRenderTexture() and markDirty() methods
- Implemented clip_children property for UIFrame
- Python-accessible boolean property
- Automatic RenderTexture creation when enabled
- Proper coordinate transformation for nested frames
- Updated UIFrame::render() for clipping support
- Renders to RenderTexture when clip_children=true
- Handles nested clipping correctly
- Only re-renders when dirty flag is set
- Added comprehensive dirty flag propagation
- All property setters mark frame as dirty
- Size changes recreate RenderTexture
- Animation system integration
- Created tests for clipping functionality
- Basic clipping test with visual verification
- Advanced nested clipping test
- Dynamic resize handling test
This is Phase 1 of the RenderTexture overhaul, providing the foundation
for advanced rendering effects like blur, glow, and viewport rendering.
Author: John McCardle <mccardle.john@gmail.com>
docs: create RenderTexture overhaul design document
- Comprehensive design for Issue #6 implementation
- Opt-in architecture to maintain backward compatibility
- Phased implementation plan with clear milestones
- Performance considerations and risk mitigation
- API design for clipping and future effects
Also includes Grid background color test
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): add customizable background_color property (#50)
- Added sf::Color background_color member with default dark gray
- Python property getter/setter for background_color
- Animation support for individual color components (r/g/b/a)
- Replaces hardcoded clear color in render method
- Test demonstrates color changes and property access
Closes #50
Author: John McCardle <mccardle.john@gmail.com>
docs: update roadmap for Phase 6 preparation
- Mark Phase 5 (Window/Scene Architecture) as complete
- Update issue statuses (#34, #61, #1, #105 completed)
- Add Phase 6 implementation strategy for RenderTexture overhaul
- Archive Phase 5 test files to .archive/
- Identify quick wins and technical approach for rendering work
Author: John McCardle <mccardle.john@gmail.com>
feat(Phase 5): Complete Window/Scene Architecture
- Window singleton with properties (resolution, fullscreen, vsync, title)
- OOP Scene support with lifecycle methods (on_enter, on_exit, on_keypress, update)
- Window resize events trigger scene.on_resize callbacks
- Scene transitions (fade, slide_left/right/up/down) with smooth animations
- Full integration of Python Scene objects with C++ engine
All Phase 5 tasks (#34, #1, #61, #105) completed successfully.
Author: John McCardle <mccardle.john@gmail.com>
research: SFML 3.0 migration analysis
- Analyzed SFML 3.0 breaking changes (event system, scoped enums, C++17)
- Assessed migration impact on McRogueFace (40+ files affected)
- Evaluated timing relative to mcrfpy.sfml module plans
- Recommended deferring migration until after mcrfpy.sfml implementation
- Created SFML_3_MIGRATION_RESEARCH.md with comprehensive strategy
Author: John McCardle <mccardle.john@gmail.com>
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
Author: John McCardle <mccardle.john@gmail.com>
feat: add basic profiling/metrics system (#104)
- Add ProfilingMetrics struct to track performance data
- Track frame time (current and 60-frame rolling average)
- Calculate FPS from average frame time
- Count draw calls, UI elements, and visible elements per frame
- Track total runtime and current frame number
- PyScene counts elements during render
- Expose metrics via mcrfpy.getMetrics() returning dict
This provides basic performance monitoring capabilities for
identifying bottlenecks and optimizing rendering performance.
Author: John McCardle <mccardle.john@gmail.com>
fix: improve click handling with proper z-order and coordinate transforms
- UIFrame: Fix coordinate transformation (subtract parent pos, not add)
- UIFrame: Check children in reverse order (highest z-index first)
- UIFrame: Skip invisible elements entirely
- PyScene: Sort elements by z-index before checking clicks
- PyScene: Stop at first element that handles the click
- UIGrid: Implement entity click detection with grid coordinate transform
- UIGrid: Check entities in reverse order, return sprite as target
Click events now correctly respect z-order (top elements get priority),
handle coordinate transforms for nested frames, and support clicking
on grid entities. Elements without click handlers are transparent to
clicks, allowing elements below to receive them.
Note: Click testing requires non-headless mode due to PyScene limitation.
feat: implement name system for finding UI elements (#39/40/41)
- Add 'name' property to UIDrawable base class
- All UI elements (Frame, Caption, Sprite, Grid, Entity) support .name
- Entity delegates name to its sprite member
- Add find(name, scene=None) function for exact match search
- Add findAll(pattern, scene=None) with wildcard support (* matches any sequence)
- Both functions search recursively through Frame children and Grid entities
- Comprehensive test coverage for all functionality
This provides a simple way to find UI elements by name in Python scripts,
supporting both exact matches and wildcard patterns.
Author: John McCardle <mccardle.john@gmail.com>
fix: prevent segfault when closing window via X button
- Add cleanup() method to GameEngine to clear Python references before destruction
- Clear timers and McRFPy_API references in proper order
- Call cleanup() at end of run loop and in destructor
- Ensure cleanup is only called once per GameEngine instance
Also includes:
- Fix audio ::stop() calls (already in place, OpenAL warning is benign)
- Add Caption support for x, y keywords (e.g. Caption("text", x=5, y=10))
- Refactor UIDrawable_methods.h into UIBase.h for better organization
- Move UIEntity-specific implementations to UIEntityPyMethods.h
Author: John McCardle <mccardle.john@gmail.com>
feat: stabilize test suite and add UIDrawable methods
- Add visible, opacity properties to all UI classes (#87, #88)
- Add get_bounds(), move(), resize() methods to UIDrawable (#89, #98)
- Create UIDrawable_methods.h with template implementations
- Fix test termination issues - all tests now exit properly
- Fix test_sprite_texture_swap.py click handler signature
- Fix test_drawable_base.py segfault in headless mode
- Convert audio objects to pointers for cleanup (OpenAL warning persists)
- Remove debug print statements from UICaption
- Special handling for UIEntity to delegate drawable methods to sprite
All test files are now "airtight" - they complete successfully,
terminate on their own, and handle edge cases properly.
Author: John McCardle <mccardle.john@gmail.com>
docs: add Phase 1-3 completion summary
- Document all completed tasks across three phases
- Show before/after API improvements
- Highlight technical achievements
- Outline next steps for Phase 4-7
Author: John McCardle <mccardle.john@gmail.com>
feat: implement mcrfpy.Timer object with pause/resume/cancel capabilities closes #103
- Created PyTimer.h/cpp with object-oriented timer interface
- Enhanced PyTimerCallable with pause/resume state tracking
- Added timer control methods: pause(), resume(), cancel(), restart()
- Added timer properties: interval, remaining, paused, active, callback
- Fixed timing logic to prevent rapid catch-up after resume
- Timer objects automatically register with game engine
- Added comprehensive test demonstrating all functionality
Author: John McCardle <mccardle.john@gmail.com>
feat(Color): add helper methods from_hex, to_hex, lerp closes #94
- Add Color.from_hex(hex_string) class method for creating colors from hex
- Support formats: #RRGGBB, RRGGBB, #RRGGBBAA, RRGGBBAA
- Add color.to_hex() to convert Color to hex string
- Add color.lerp(other, t) for smooth color interpolation
- Comprehensive test coverage for all methods
Author: John McCardle <mccardle.john@gmail.com>
fix: properly configure UTF-8 encoding for Python stdio
- Use PyConfig to set stdio_encoding="UTF-8" during initialization
- Set stdio_errors="surrogateescape" for robust handling
- Configure in both init_python() and init_python_with_config()
- Cleaner solution than wrapping streams after initialization
- Fixes UnicodeEncodeError when printing unicode characters
Author: John McCardle <mccardle.john@gmail.com>
feat(Vector): implement arithmetic operations closes #93
- Add PyNumberMethods with add, subtract, multiply, divide, negate, absolute
- Add rich comparison for equality/inequality checks
- Add boolean check (zero vector is False)
- Implement vector methods: magnitude(), normalize(), dot(), distance_to(), angle(), copy()
- Fix UIDrawable::get_click() segfault when click_callable is null
- Comprehensive test coverage for all arithmetic operations
Author: John McCardle <mccardle.john@gmail.com>
feat: Complete position argument standardization for all UI classes
- Frame and Sprite now support pos keyword override
- Entity now accepts x,y arguments (was pos-only before)
- All UI classes now consistently support:
- (x, y) positional
- ((x, y)) tuple
- x=x, y=y keywords
- pos=(x,y) keyword
- pos=Vector keyword
- Improves API consistency and flexibility
Author: John McCardle <mccardle.john@gmail.com>
feat: Standardize position arguments across all UI classes
- Create PyPositionHelper for consistent position parsing
- Grid.at() now accepts (x,y), ((x,y)), x=x, y=y, pos=(x,y)
- Caption now accepts x,y args in addition to pos
- Grid init fully supports keyword arguments
- Maintain backward compatibility for all formats
- Consistent error messages across classes
Author: John McCardle <mccardle.john@gmail.com>
feat: Add Entity.die() method for lifecycle management closes #30
- Remove entity from its grid's entity list
- Clear grid reference after removal
- Safe to call multiple times (no-op if not on grid)
- Works with shared_ptr entity management
Author: John McCardle <mccardle.john@gmail.com>
perf: Skip out-of-bounds entities during Grid rendering closes #52
- Add visibility bounds check in entity render loop
- Skip entities outside view with 1 cell margin
- Improves performance for large grids with many entities
- Bounds check considers zoom and pan settings
Author: John McCardle <mccardle.john@gmail.com>
verify: Sprite texture swapping functionality closes #19
- Texture property getter/setter already implemented
- Position/scale preservation during swap confirmed
- Type validation for texture assignment working
- Tests verify functionality is complete
Author: John McCardle <mccardle.john@gmail.com>
feat: Grid size tuple support closes #90
- Add grid_size keyword parameter to Grid.__init__
- Accept tuple or list of two integers
- Override grid_x/grid_y if grid_size provided
- Maintain backward compatibility
- Add comprehensive test coverage
Author: John McCardle <mccardle.john@gmail.com>
feat: Phase 1 - safe constructors and _Drawable foundation
Closes #7 - Make all UI class constructors safe:
- Added safe default constructors for UISprite, UIGrid, UIEntity, UICaption
- Initialize all members to predictable values
- Made Python init functions accept no arguments
- Added x,y properties to UIEntity
Closes #71 - Create _Drawable Python base class:
- Created PyDrawable.h/cpp with base type (not yet inherited by UI types)
- Registered in module initialization
Closes #87 - Add visible property:
- Added bool visible=true to UIDrawable base class
- All render methods check visibility before drawing
Closes #88 - Add opacity property:
- Added float opacity=1.0 to UIDrawable base class
- UICaption and UISprite apply opacity to alpha channel
Closes #89 - Add get_bounds() method:
- Virtual method returns sf::FloatRect(x,y,w,h)
- Implemented in Frame, Caption, Sprite, Grid
Closes #98 - Add move() and resize() methods:
- move(dx,dy) for relative movement
- resize(w,h) for absolute sizing
- Caption resize is no-op (size controlled by font)
Author: John McCardle <mccardle.john@gmail.com>
docs: comprehensive alpha_streamline_2 plan and strategic vision
- Add 7-phase development plan for alpha_streamline_2 branch
- Define architectural dependencies and critical path
- Identify new issues needed (Timer objects, event system, etc.)
- Add strategic vision document with 3 transformative directions
- Timeline: 10-12 weeks to solid Beta foundation
Author: John McCardle <mccardle.john@gmail.com>
feat(Grid): flexible at() method arguments
- Support tuple argument: grid.at((x, y))
- Support keyword arguments: grid.at(x=5, y=3)
- Support pos keyword: grid.at(pos=(2, 8))
- Maintain backward compatibility with grid.at(x, y)
- Add comprehensive error handling for invalid arguments
Improves API ergonomics and Python-like flexibility
2025-07-09 22:41:15 -04:00
value = position ;
Squashed commit of the following: [interpreter_mode]
closes #63
closes #69
closes #59
closes #47
closes #2
closes #3
closes #33
closes #27
closes #73
closes #74
closes #78
I'd like to thank Claude Code for ~200-250M total tokens and 500-700k output tokens
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
commit 9bd1561bfc9b02d8db71b5d9390ef2631fac5b28
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 11:20:07 2025 -0400
Alpha 0.1 release
- Move RenderTexture (#6) out of alpha requirements, I don't need it
that badly
- alpha blockers resolved:
* Animation system (#59)
* Z-order rendering (#63)
* Python Sequence Protocol (#69)
* New README (#47)
* Removed deprecated methods (#2, #3)
🍾 McRogueFace 0.1.0
commit 43321487eb762e17639ba4113322b6f5df71a8d9
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:36:09 2025 -0400
Issue #63 (z-order rendering) complete
- Archive z-order test files
commit 90c318104bfb31ab4c741702e6661e6bf7e4d19c
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 10:34:06 2025 -0400
Fix Issue #63: Implement z-order rendering with dirty flag optimization
- Add dirty flags to PyScene and UIFrame to track when sorting is needed
- Implement lazy sorting - only sort when z_index changes or elements are added/removed
- Make Frame children respect z_index (previously rendered in insertion order only)
- Update UIDrawable::set_int to notify when z_index changes
- Mark collections dirty on append, remove, setitem, and slice operations
- Remove per-frame vector copy in PyScene::render for better performance
commit e4482e7189095d88eec1e2ec55e01e271ed4f55f
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 01:58:03 2025 -0400
Implement complete Python Sequence Protocol for collections (closes #69)
Major implementation of the full sequence protocol for both UICollection
and UIEntityCollection, making them behave like proper Python sequences.
Core Features Implemented:
- __setitem__ (collection[i] = value) with type validation
- __delitem__ (del collection[i]) with proper cleanup
- __contains__ (item in collection) by C++ pointer comparison
- __add__ (collection + other) returns Python list
- __iadd__ (collection += other) with full validation before modification
- Negative indexing support throughout
- Complete slice support (getting, setting, deletion)
- Extended slices with step \!= 1
- index() and count() methods
- Type safety enforced for all operations
UICollection specifics:
- Accepts Frame, Caption, Sprite, and Grid objects only
- Preserves z_index when replacing items
- Auto-assigns z_index on append (existing behavior maintained)
UIEntityCollection specifics:
- Accepts Entity objects only
- Manages grid references on add/remove/replace
- Uses std::list iteration with std::advance()
Also includes:
- Default value support for constructors:
- Caption accepts None for font (uses default_font)
- Grid accepts None for texture (uses default_texture)
- Sprite accepts None for texture (uses default_texture)
- Entity accepts None for texture (uses default_texture)
This completes Issue #69, removing it as an Alpha Blocker.
commit 70cf44f8f044ed49544dd9444245115187d3b318
Author: John McCardle <mccardle.john@gmail.com>
Date: Sat Jul 5 00:56:42 2025 -0400
Implement comprehensive animation system (closes #59)
- Add Animation class with 30+ easing functions (linear, ease in/out, quad, cubic, elastic, bounce, etc.)
- Add property system to all UI classes for animation support:
- UIFrame: position, size, colors (including individual r/g/b/a components)
- UICaption: position, size, text, colors
- UISprite: position, scale, sprite_number (with sequence support)
- UIGrid: position, size, camera center, zoom
- UIEntity: position, sprite properties
- Create AnimationManager singleton for frame-based updates
- Add Python bindings through PyAnimation wrapper
- Support for delta animations (relative values)
- Fix segfault when running scripts directly (mcrf_module initialization)
- Fix headless/windowed mode behavior to respect --headless flag
- Animations run purely in C++ without Python callbacks per frame
All UI properties are now animatable with smooth interpolation and professional easing curves.
commit 05bddae5112f2b5949a9d2b32dd3dc2bf4656837
Author: John McCardle <mccardle.john@gmail.com>
Date: Fri Jul 4 06:59:02 2025 -0400
Update comprehensive documentation for Alpha release (Issue #47)
- Completely rewrote README.md to reflect current features
- Updated GitHub Pages documentation site with:
- Modern landing page highlighting Crypt of Sokoban
- Comprehensive API reference (2700+ lines) with exhaustive examples
- Updated getting-started guide with installation and first game tutorial
- 8 detailed tutorials covering all major game systems
- Quick reference cheat sheet for common operations
- Generated documentation screenshots showing UI elements
- Fixed deprecated API references and added new features
- Added automation API documentation
- Included Python 3.12 requirement and platform-specific instructions
Note: Text rendering in headless mode has limitations for screenshots
commit af6a5e090b9f52e3328294a988bdc18ff4b6c981
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:58 2025 -0400
Update ROADMAP.md to reflect completion of Issues #2 and #3
- Marked both issues as completed with the removal of deprecated action system
- Updated open issue count from ~50 to ~48
- These were both Alpha blockers, bringing us closer to release
commit 281800cd2345cc57024c9bcdd18860d2bb8db027
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:43:22 2025 -0400
Remove deprecated registerPyAction/registerInputAction system (closes #2, closes #3)
This is our largest net-negative commit yet\! Removed the entire deprecated
action registration system that provided unnecessary two-step indirection:
keyboard → action string → Python callback
Removed components:
- McRFPy_API::_registerPyAction() and _registerInputAction() methods
- McRFPy_API::callbacks map for storing Python callables
- McRFPy_API::doAction() method for executing callbacks
- ACTIONPY macro from Scene.h for detecting "_py" suffixed actions
- Scene::registerActionInjected() and unregisterActionInjected() methods
- tests/api_registerPyAction_issue2_test.py (tested deprecated functionality)
The game now exclusively uses keypressScene() for keyboard input handling,
which is simpler and more direct. Also commented out the unused _camFollow
function that referenced non-existent do_camfollow variable.
commit cc8a7d20e8ea5c7b32cad2565cc9e85e27bef147
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:59 2025 -0400
Clean up temporary test files
commit ff83fd8bb159cd2e7d9056379576d147bd99656b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:13:46 2025 -0400
Update ROADMAP.md to reflect massive progress today
- Fixed 12+ critical bugs in a single session
- Implemented 3 missing features (Entity.index, EntityCollection.extend, sprite validation)
- Updated Phase 1 progress showing 11 of 12 items complete
- Added detailed summary of today's achievements with issue numbers
- Emphasized test-driven development approach used throughout
commit dae400031fe389025955bee423f9b327fd596b1d
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:12:29 2025 -0400
Remove deprecated player_input and turn-based functions for Issue #3
Removed the commented-out player_input(), computerTurn(), and playerTurn()
functions that were part of the old turn-based system. These are no longer
needed as input is now handled through Scene callbacks.
Partial fix for #3
commit cb0130b46eb873d7a38b4647b0f3d2698f234ab9
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:09:06 2025 -0400
Implement sprite index validation for Issue #33
Added validation to prevent setting sprite indices outside the valid
range for a texture. The implementation:
- Adds getSpriteCount() method to PyTexture to expose total sprites
- Validates sprite_number setter to ensure index is within bounds
- Provides clear error messages showing valid range
- Works for both Sprite and Entity objects
closes #33
commit 1e7f5e9e7e9e4d6e9494ba6c19f1ae0c5282b449
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:05:47 2025 -0400
Implement EntityCollection.extend() method for Issue #27
Added extend() method to EntityCollection that accepts any iterable
of Entity objects and adds them all to the collection. The method:
- Accepts lists, tuples, generators, or any iterable
- Validates all items are Entity objects
- Sets the grid association for each added entity
- Properly handles errors and empty iterables
closes #27
commit 923350137d148c56e617eae966467c77617c131b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 21:02:14 2025 -0400
Implement Entity.index() method for Issue #73
Added index() method to Entity class that returns the entity's
position in its parent grid's entity collection. This enables
proper entity removal patterns using entity.index().
commit 6134869371cf4e7ae79515690960a563fd0db40e
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:41:03 2025 -0400
Add validation to keypressScene() for non-callable arguments
Added PyCallable_Check validation to ensure keypressScene() only
accepts callable objects. Now properly raises TypeError with a
clear error message when passed non-callable arguments like
strings, numbers, None, or dicts.
commit 4715356b5e760b9fd8f2087565adaab2fb94573b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:31:36 2025 -0400
Fix Sprite texture setter 'error return without exception set'
Implemented the missing UISprite::set_texture method to properly:
- Validate the input is a Texture instance
- Update the sprite's texture using setTexture()
- Return appropriate error messages for invalid inputs
The setter now works correctly and no longer returns -1 without
setting an exception.
commit 6dd1cec600efd3b9f44f67968a23c88e05e19ec8
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 20:27:32 2025 -0400
Fix Entity property setters and PyVector implementation
Fixed the 'new style getargs format' error in Entity property setters by:
- Implementing PyObject_to_sfVector2f/2i using PyVector::from_arg
- Adding proper error checking in Entity::set_position
- Implementing PyVector get_member/set_member for x/y properties
- Fixing PyVector::from_arg to handle non-tuple arguments correctly
Now Entity.pos and Entity.sprite_number setters work correctly with
proper type validation.
commit f82b861bcdffa9d3df69bd29c7c88be2a30c9ba5
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:48:33 2025 -0400
Fix Issue #74: Add missing Grid.grid_y property
Added individual grid_x and grid_y getter properties to the Grid class
to complement the existing grid_size property. This allows direct access
to grid dimensions and fixes error messages that referenced these
properties before they existed.
closes #74
commit 59e6f8d53dda6938914ce854249925b3ce7f41f4
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:42:32 2025 -0400
Fix Issue #78: Middle mouse click no longer sends 'C' keyboard event
The bug was caused by accessing event.key.code on a mouse event without
checking the event type first. Since SFML uses a union for events, this
read garbage data. The middle mouse button value (2) coincidentally matched
the keyboard 'C' value (2), causing the spurious keyboard event.
Fixed by adding event type check before accessing key-specific fields.
Only keyboard events (KeyPressed/KeyReleased) now trigger key callbacks.
Test added to verify middle clicks no longer generate keyboard events.
Closes #78
commit 1c71d8d4f743900bf2bef097b3d1addf64dbe04a
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:36:15 2025 -0400
Fix Grid to support None/null texture and fix error message bug
- Allow Grid to be created with None as texture parameter
- Use default cell dimensions (16x16) when no texture provided
- Skip sprite rendering when texture is null, but still render colors
- Fix issue #77: Corrected copy/paste error in Grid.at() error messages
- Grid now functional for color-only rendering and entity positioning
Test created to verify Grid works without texture, showing colored cells.
Closes #77
commit 18cfe93a44a9f4dcde171f442dc3d56711a0906b
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 19:25:49 2025 -0400
Fix --exec interactive prompt bug and create comprehensive test suite
Major fixes:
- Fixed --exec entering Python REPL instead of game loop
- Resolved screenshot transparency issue (requires timer callbacks)
- Added debug output to trace Python initialization
Test suite created:
- 13 comprehensive tests covering all Python-exposed methods
- Tests use timer callback pattern for proper game loop interaction
- Discovered multiple critical bugs and missing features
Critical bugs found:
- Grid class segfaults on instantiation (blocks all Grid functionality)
- Issue #78 confirmed: Middle mouse click sends 'C' keyboard event
- Entity property setters have argument parsing errors
- Sprite texture setter returns improper error
- keypressScene() segfaults on non-callable arguments
Documentation updates:
- Updated CLAUDE.md with testing guidelines and TDD practices
- Created test reports documenting all findings
- Updated ROADMAP.md with test results and new priorities
The Grid segfault is now the highest priority as it blocks all Grid-based functionality.
commit 9ad0b6850d5f77d93c22eb52cbeb4d8442e77918
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 15:55:24 2025 -0400
Update ROADMAP.md to reflect Python interpreter and automation API progress
- Mark #32 (Python interpreter behavior) as 90% complete
- All major Python flags implemented: -h, -V, -c, -m, -i
- Script execution with proper sys.argv handling works
- Only stdin (-) support missing
- Note that new automation API enables:
- Automated UI testing capabilities
- Demo recording and playback
- Accessibility testing support
- Flag issues #53 and #45 as potentially aided by automation API
commit 7ec4698653383cb28f0115d1abf1db0a500257ec
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:57:59 2025 -0400
Update ROADMAP.md to remove closed issues
- Remove #72 (iterator improvements - closed)
- Remove #51 (UIEntity derive from UIDrawable - closed)
- Update issue counts: 64 open issues from original 78
- Update dependencies and references to reflect closed issues
- Clarify that core iterators are complete, only grid points remain
commit 68c1a016b0e1d1b438c926f5576e5650b9617fe1
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 14:27:01 2025 -0400
Implement --exec flag and PyAutoGUI-compatible automation API
- Add --exec flag to execute multiple scripts before main program
- Scripts are executed in order and share Python interpreter state
- Implement full PyAutoGUI-compatible automation API in McRFPy_Automation
- Add screenshot, mouse control, keyboard input capabilities
- Fix Python initialization issues when multiple scripts are loaded
- Update CommandLineParser to handle --exec with proper sys.argv management
- Add comprehensive examples and documentation
This enables automation testing by allowing test scripts to run alongside
games using the same Python environment. The automation API provides
event injection into the SFML render loop for UI testing.
Closes #32 partially (Python interpreter emulation)
References automation testing requirements
commit 763fa201f041a0d32bc45695c1bbbac5590adba0
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 10:43:17 2025 -0400
Python command emulation
commit a44b8c93e938ca0c58cff7e5157293d97d182a39
Author: John McCardle <mccardle.john@gmail.com>
Date: Thu Jul 3 09:42:46 2025 -0400
Prep: Cleanup for interpreter mode
2025-07-05 12:04:20 -04:00
return true ;
}
else if ( name = = " size " ) {
value = box . getSize ( ) ;
return true ;
}
else if ( name = = " center " ) {
value = sf : : Vector2f ( center_x , center_y ) ;
return true ;
}
return false ;
}