# McRogueFace - Development Roadmap ## Project Status: Post-7DRL 2025 "Crypt of Sokoban" **Current State**: Successful 7DRL completion with Python/C++ game engine **Latest Commit**: Working on test suite and critical bug fixes **Branch**: interpreter_mode (test suite created, critical fixes implemented) **Open Issues**: 64 catalogued issues from Gitea instance (14 closed) --- ## ๐Ÿ”ง CURRENT WORK: Python Interpreter Mode & Automation API ### Branch: interpreter_mode **Status**: Actively implementing Python interpreter emulation features #### Completed Features: - [x] **--exec flag implementation** - Execute multiple scripts before main program - Scripts execute in order and share Python interpreter state - Proper sys.argv handling for main script execution - Compatible with -i (interactive), -c (command), and -m (module) modes - [x] **PyAutoGUI-compatible Automation API** - Full automation testing capability - Screenshot capture: `automation.screenshot(filename)` - Mouse control: `click()`, `moveTo()`, `dragTo()`, `scroll()` - Keyboard input: `typewrite()`, `hotkey()`, `keyDown()`, `keyUp()` - Event injection into SFML render loop - **Enables**: Automated UI testing, demo recording/playback, accessibility testing #### Architectural Decisions: 1. **Single-threaded design maintained** - All Python runs in main thread between frames 2. **Honor system for scripts** - Scripts must return control to C++ render loop 3. **Shared Python state** - All --exec scripts share the same interpreter 4. **No threading complexity** - Chose simplicity over parallelism (see THREADING_FOOTGUNS.md) #### Key Files Created: - `src/McRFPy_Automation.h/cpp` - Complete automation API implementation - `EXEC_FLAG_DOCUMENTATION.md` - Usage guide and examples - `AUTOMATION_ARCHITECTURE_REPORT.md` - Design analysis and alternatives - Multiple example scripts demonstrating automation patterns #### Addresses: - **#32** - Executable behave like `python` command (90% complete - all major Python interpreter flags implemented) #### Test Suite Results (2025-07-03): Created comprehensive test suite with 13 tests covering all Python-exposed methods: **โœ… Fixed Issues:** - Fixed `--exec` Python interactive prompt bug (was entering REPL instead of game loop) - Resolved screenshot transparency issue (must use timer callbacks for rendered content) - Updated CLAUDE.md with testing guidelines and patterns **โŒ Critical Bugs Found:** 1. **SEGFAULT**: Grid class crashes on instantiation (blocks all Grid functionality) 2. **#78 CONFIRMED**: Middle mouse click sends 'C' keyboard event 3. **Entity property setters**: "new style getargs format" error 4. **Sprite texture setter**: Returns "error return without exception set" 5. **keypressScene()**: Segfaults on non-callable arguments **๐Ÿ“‹ Missing Features Confirmed:** - #73: Entity.index() method - #27: EntityCollection.extend() method - #41: UICollection.find(name) method - #38: Frame 'children' constructor parameter - #33: Sprite index validation - #69: Partial Sequence Protocol (no slicing, 'in' operator) --- ## ๐Ÿšง IMMEDIATE PRIORITY: Critical Bugfixes & Iterator Completion ### ๐Ÿ”ฅ Critical Bugfixes (Complete First) - [ ] **CRITICAL: Grid Segfault** - Grid class crashes on instantiation (blocks ALL Grid functionality) - *High Priority* - [ ] **#78** - Middle Mouse Click sends "C" keyboard event to scene event handler - *Confirmed Bug* - [ ] **#77** - Fix error message copy/paste bug (`x value out of range (0, Grid.grid_y)`) - *Isolated Fix* - [ ] **#74** - Add missing `Grid.grid_y` property referenced in error messages - *Isolated Fix* - [ ] **#37** - Fix Windows build module import from "scripts" directory - *Isolated Fix* - [ ] **Entity Property Setters** - Fix "new style getargs format" error - *Multiple Fixes* - [ ] **Sprite Texture Setter** - Fix "error return without exception set" - *Isolated Fix* - [ ] **keypressScene() Validation** - Add proper error handling for non-callable arguments - *Isolated Fix* ### ๐Ÿ”„ Complete Iterator System **Status**: Core iterators complete (#72 closed), Grid point iterators still pending - [ ] **Grid Point Iterator Implementation** - Complete the remaining grid iteration work - [ ] **#73** - Add `entity.index()` method for collection removal - *Isolated Fix* - [ ] **#69** โš ๏ธ **Alpha Blocker** - Refactor all collections to use Python Sequence Protocol - *Extensive Overhaul* **Dependencies**: Grid point iterators โ†’ #73 entity.index() โ†’ #69 Sequence Protocol overhaul --- ## ๐ŸŽฏ ALPHA 0.1 RELEASE BLOCKERS (6 Issues) ### โš ๏ธ Must Complete Before Alpha Release - [ ] **#69** - Collections use Python Sequence Protocol - *Extensive Overhaul* - [ ] **#63** - Z-order rendering for UIDrawables - *Multiple Integrations* - [ ] **#59** - Animation system for arbitrary UIDrawable fields - *Extensive Overhaul* - [ ] **#6** - RenderTexture concept for all UIDrawables - *Extensive Overhaul* - [ ] **#47** - New README.md for Alpha release - *Isolated Fix* - [ ] **#3** - Remove deprecated `McRFPy_API::player_input` - *Isolated Fix* - [ ] **#2** - Review `registerPyAction` necessity - *Isolated Fix* --- ## ๐Ÿ—‚ ISSUE TRIAGE BY SYSTEM (78 Total Issues) ### ๐ŸŽฎ Core Engine Systems #### Iterator/Collection System (2 issues) - [ ] **#73** - Entity index() method for removal - *Isolated Fix* - [ ] **#69** โš ๏ธ **Alpha Blocker** - Sequence Protocol refactor - *Extensive Overhaul* #### Python/C++ Integration (7 issues) - [ ] **#76** - UIEntity derived type preservation in collections - *Multiple Integrations* - [ ] **#71** - Drawable base class hierarchy - *Extensive Overhaul* - [ ] **#70** - PyPI wheel distribution - *Extensive Overhaul* - [~] **#32** - Executable behave like `python` command - *Extensive Overhaul* *(90% Complete: -h, -V, -c, -m, -i, script execution, sys.argv, --exec all implemented. Only stdin (-) support missing)* - [ ] **#35** - TCOD as built-in module - *Extensive Overhaul* - [ ] **#14** - Expose SFML as built-in module - *Extensive Overhaul* - [ ] **#46** - Subinterpreter threading tests - *Multiple Integrations* #### UI/Rendering System (12 issues) - [ ] **#63** โš ๏ธ **Alpha Blocker** - Z-order for UIDrawables - *Multiple Integrations* - [ ] **#59** โš ๏ธ **Alpha Blocker** - Animation system - *Extensive Overhaul* - [ ] **#6** โš ๏ธ **Alpha Blocker** - RenderTexture for all UIDrawables - *Extensive Overhaul* - [ ] **#10** - UIDrawable visibility/AABB system - *Extensive Overhaul* - [ ] **#8** - UIGrid RenderTexture viewport sizing - *Multiple Integrations* - [ ] **#9** - UIGrid RenderTexture resize handling - *Multiple Integrations* - [ ] **#52** - UIGrid skip out-of-bounds entities - *Isolated Fix* - [ ] **#50** - UIGrid background color field - *Isolated Fix* - [ ] **#19** - Sprite get/set texture methods - *Multiple Integrations* - [ ] **#17** - Move UISprite position into sf::Sprite - *Isolated Fix* - [ ] **#33** - Sprite index validation against texture range - *Isolated Fix* #### Grid/Entity System (6 issues) - [ ] **#30** - Entity/Grid association management (.die() method) - *Extensive Overhaul* - [ ] **#16** - Grid strict mode for entity knowledge/visibility - *Extensive Overhaul* - [ ] **#67** - Grid stitching for infinite worlds - *Extensive Overhaul* - [ ] **#15** - UIGridPointState cleanup and standardization - *Multiple Integrations* - [ ] **#20** - UIGrid get_grid_size standardization - *Multiple Integrations* - [ ] **#12** - GridPoint/GridPointState forbid direct init - *Isolated Fix* #### Scene/Window Management (5 issues) - [ ] **#61** - Scene object encapsulating key callbacks - *Extensive Overhaul* - [ ] **#34** - Window object for resolution/scaling - *Extensive Overhaul* - [ ] **#62** - Multiple windows support - *Extensive Overhaul* - [ ] **#49** - Window resolution & viewport controls - *Multiple Integrations* - [ ] **#1** - Scene resize event handling - *Isolated Fix* ### ๐Ÿ”ง Quality of Life Features #### UI Enhancement Features (8 issues) - [ ] **#39** - Name field on UIDrawables - *Multiple Integrations* - [ ] **#40** - `only_one` arg for unique naming - *Multiple Integrations* - [ ] **#41** - `.find(name)` method for collections - *Multiple Integrations* - [ ] **#38** - `children` arg for Frame initialization - *Isolated Fix* - [ ] **#42** - Click callback arg for UIDrawable init - *Isolated Fix* - [ ] **#27** - UIEntityCollection.extend() method - *Isolated Fix* - [ ] **#28** - UICollectionIter for scene ui iteration - *Isolated Fix* - [ ] **#26** - UIEntityCollectionIter implementation - *Isolated Fix* ### ๐Ÿงน Refactoring & Cleanup #### Code Cleanup (7 issues) - [ ] **#3** โš ๏ธ **Alpha Blocker** - Remove `McRFPy_API::player_input` - *Isolated Fix* - [ ] **#2** โš ๏ธ **Alpha Blocker** - Review `registerPyAction` necessity - *Isolated Fix* - [ ] **#7** - Remove unsafe no-argument constructors - *Multiple Integrations* - [ ] **#21** - PyUIGrid dealloc cleanup - *Isolated Fix* - [ ] **#75** - REPL thread separation from SFML window - *Multiple Integrations* ### ๐Ÿ“š Demo & Documentation #### Documentation (2 issues) - [ ] **#47** โš ๏ธ **Alpha Blocker** - Alpha release README.md - *Isolated Fix* - [ ] **#48** - Dependency compilation documentation - *Isolated Fix* #### Demo Projects (6 issues) - [ ] **#54** - Jupyter notebook integration demo - *Multiple Integrations* - [ ] **#55** - Hunt the Wumpus AI demo - *Multiple Integrations* - [ ] **#53** - Web interface input demo - *Multiple Integrations* *(New automation API could help)* - [ ] **#45** - Accessibility mode demos - *Multiple Integrations* *(New automation API could help test)* - [ ] **#36** - Dear ImGui integration tests - *Extensive Overhaul* - [ ] **#65** - Python Explorer scene (replaces uitest) - *Extensive Overhaul* --- ## ๐ŸŽฏ RECOMMENDED TRIAGE SEQUENCE ### Phase 1: Foundation Stabilization (1-2 weeks) ``` โœ… COMPLETE AS OF 2025-01-03: 1. โœ… Fix Grid Segfault - Grid now supports None/null textures 2. โœ… Fix #78 Middle Mouse Click bug - Event type checking added 3. โœ… Fix Entity/Sprite property setters - PyVector conversion fixed 4. โœ… Fix #77 - Error message copy/paste bug fixed 5. โœ… Fix #74 - Grid.grid_y property added 6. โœ… Fix keypressScene() validation - Now rejects non-callable 7. โœ… Fix Sprite texture setter - No longer returns error without exception 8. โœ… Fix PyVector x/y properties - Were returning None REMAINING IN PHASE 1: 9. Fix #73 - Entity.index() method for removal 10. Fix #27 - EntityCollection.extend() method 11. Fix #33 - Sprite index validation 12. Alpha Blockers (#3, #2) - Remove deprecated methods ``` ### Phase 2: Alpha Release Preparation (4-6 weeks) ``` 1. Collections Sequence Protocol (#69) - Major refactor, alpha blocker 2. Z-order rendering (#63) - Essential UI improvement, alpha blocker 3. RenderTexture overhaul (#6) - Core rendering improvement, alpha blocker 4. Animation system (#59) - Major feature, alpha blocker 5. Documentation (#47, #48) - Complete alpha release docs ``` ### Phase 3: Engine Architecture (6-8 weeks) ``` 1. Drawable base class (#71) - Clean up inheritance patterns 2. Entity/Grid associations (#30) - Proper lifecycle management 3. Window object (#34) - Scene/window architecture 4. UIDrawable visibility (#10) - Rendering optimization ``` ### Phase 4: Advanced Features (8-12 weeks) ``` 1. Grid strict mode (#16) - Entity knowledge/visibility system 2. SFML/TCOD integration (#14, #35) - Expose native libraries 3. Scene object refactor (#61) - Better input handling 4. Name-based finding (#39, #40, #41) - UI element management 5. Demo projects (#54, #55, #36) - Showcase capabilities ``` ### Ongoing/Low Priority ``` - PyPI distribution (#70) - Community access - Multiple windows (#62) - Advanced use cases - Grid stitching (#67) - Infinite world support - Accessibility (#45) - Important but not blocking - Subinterpreter tests (#46) - Performance research ``` --- ## ๐Ÿ“Š DIFFICULTY ASSESSMENT SUMMARY **Isolated Fixes (24 issues)**: Single file/function changes - Bugfixes: #77, #74, #37, #78 - Simple features: #73, #52, #50, #33, #17, #38, #42, #27, #28, #26, #12, #1 - Cleanup: #3, #2, #21, #47, #48 **Multiple Integrations (28 issues)**: Cross-system changes - UI/Rendering: #63, #8, #9, #19, #39, #40, #41 - Grid/Entity: #15, #20, #76, #46, #49, #75 - Features: #54, #55, #53, #45, #7 **Extensive Overhauls (26 issues)**: Major architectural changes - Core Systems: #69, #59, #6, #10, #30, #16, #67, #61, #34, #62 - Integration: #71, #70, #32, #35, #14 - Advanced: #36, #65 --- ## ๐ŸŽฎ STRATEGIC DIRECTION ### Engine Philosophy Maintained - **C++ First**: Performance-critical code stays in C++ - **Python Close Behind**: Rich scripting without frame-rate impact - **Game-Ready**: Each improvement should benefit actual game development ### Architecture Goals 1. **Clean Inheritance**: Drawable โ†’ UI components, proper type preservation 2. **Collection Consistency**: Uniform iteration, indexing, and search patterns 3. **Resource Management**: RAII everywhere, proper lifecycle handling 4. **Multi-Platform**: Windows/Linux feature parity maintained ### Success Metrics for Alpha 0.1 - [ ] All 7 Alpha Blocker issues resolved - [ ] Grid point iteration complete and tested - [ ] Clean build on Windows and Linux - [ ] Documentation sufficient for external developers - [ ] At least one compelling demo (Wumpus or Jupyter integration) --- ## ๐Ÿ“š REFERENCES & CONTEXT **Issue Dependencies** (Key Chains): - Iterator System: Grid points โ†’ #73 โ†’ #69 (Alpha Blocker) - UI Hierarchy: #71 โ†’ #63 (Alpha Blocker) - Rendering: #6 (Alpha Blocker) โ†’ #8, #9 โ†’ #10 - Entity System: #30 โ†’ #16 โ†’ #67 - Window Management: #34 โ†’ #49, #61 โ†’ #62 **Commit References**: - 167636c: Iterator improvements (UICollection/UIEntityCollection complete) - Recent work: 7DRL 2025 completion, RPATH updates, console improvements **Architecture Files**: - Iterator patterns: src/UICollection.cpp, src/UIGrid.cpp - Python integration: src/McRFPy_API.cpp, src/PyObjectUtils.h - Game implementation: src/scripts/ (Crypt of Sokoban complete game) --- *Last Updated: 2025-07-03* *Total Open Issues: 64* (from original 78) *Alpha Blockers: 7* *Current Work: Python interpreter mode features (--exec flag, automation API)* *Next Session: Continue interpreter mode or switch to critical bugfixes*