# McRogueFace - Development Roadmap

## Project Status: Post-7DRL 2025 "Crypt of Sokoban"

**Current State**: Successful 7DRL completion with Python/C++ game engine  
**Latest Update**: Z-order rendering complete! Issue #63 resolved (2025-07-05)  
**Branch**: interpreter_mode (full sequence protocol for collections + default values)  
**Open Issues**: ~46 remaining from original 64 (closed 16 + fixed 14 previously)

---

## Recent Achievements

### 2025-07-05: Z-order Rendering Complete! 🎉
**Issue #63 Resolved**: Consistent z-order rendering with performance optimization
- Dirty flag pattern prevents unnecessary per-frame sorting
- Lazy sorting for both Scene elements and Frame children
- Frame children now respect z_index (fixed inconsistency)
- Automatic dirty marking on z_index changes and collection modifications
- Performance: O(1) check for static scenes vs O(n log n) every frame

### 2025-07-05: Python Sequence Protocol Complete! 🎉
**Issue #69 Resolved**: Full sequence protocol implementation for collections
- Complete __setitem__, __delitem__, __contains__ support
- Slice operations with extended slice support (step != 1)
- Concatenation (+) and in-place concatenation (+=) with validation
- Negative indexing throughout, index() and count() methods
- Type safety: UICollection (Frame/Caption/Sprite/Grid), EntityCollection (Entity only)
- Default value support: None for texture/font parameters uses engine defaults

### 2025-07-05: Animation System Complete! 🎉
**Issue #59 Resolved**: Comprehensive animation system with 30+ easing functions
- Property-based animations for all UI classes (Frame, Caption, Sprite, Grid, Entity)
- Individual color component animation (r/g/b/a)
- Sprite sequence animation and text typewriter effects
- Pure C++ execution without Python callbacks
- Delta animation support for relative values

### 2025-01-03: Major Stability Update
**Major Cleanup**: Removed deprecated registerPyAction system (-180 lines)
**Bug Fixes**: 12 critical issues including Grid segfault, Issue #78 (middle click), Entity setters
**New Features**: Entity.index() (#73), EntityCollection.extend() (#27), Sprite validation (#33)
**Test Coverage**: Comprehensive test suite with timer callback pattern established

---

## 🔧 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)
5. **Animation system in pure C++** - All interpolation happens in C++ for performance
6. **Property-based animation** - Unified interface for all UI element properties

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

---

## 🚧 NEXT PRIORITY: Alpha Release Blockers

### Remaining Alpha Blockers (2 issues):
1. ~~**#69** - Python Sequence Protocol for collections~~ - *Completed! (2025-07-05)*
2. ~~**#63** - Z-order rendering for UIDrawables~~ - *Completed! (2025-07-05)*
3. ~~**#59** - Animation system~~ - *Completed! (2025-07-05)*
4. **#6** - RenderTexture concept - *Extensive Overhaul*
5. ~~**#47** - New README.md for Alpha release~~ - *Completed*
- [x] **#78** - Middle Mouse Click sends "C" keyboard event - *Fixed*
- [x] **#77** - Fix error message copy/paste bug - *Fixed*
- [x] **#74** - Add missing `Grid.grid_y` property - *Fixed*  
- [ ] **#37** - Fix Windows build module import from "scripts" directory - *Isolated Fix*
- [x] **Entity Property Setters** - Fix "new style getargs format" error - *Fixed*
- [x] **Sprite Texture Setter** - Fix "error return without exception set" - *Fixed*
- [x] **keypressScene() Validation** - Add proper error handling - *Fixed*

### 🔄 Complete Iterator System
**Status**: Core iterators complete (#72 closed), Grid point iterators still pending

- [ ] **Grid Point Iterator Implementation** - Complete the remaining grid iteration work
- [x] **#73** - Add `entity.index()` method for collection removal - *Fixed*
- [x] **#69** ⚠️ **Alpha Blocker** - Refactor all collections to use Python Sequence Protocol - *Completed! (2025-07-05)*

**Dependencies**: Grid point iterators → #73 entity.index() → #69 Sequence Protocol overhaul

---

## 🎯 ALPHA 0.1 RELEASE BLOCKERS (2 Remaining)

### ⚠️ Must Complete Before Alpha Release
- [x] **#69** - Collections use Python Sequence Protocol - *Completed! (2025-07-05)*
- [x] **#63** - Z-order rendering for UIDrawables - *Completed! (2025-07-05)*  
- [x] **#59** - Animation system for arbitrary UIDrawable fields - *Completed! (2025-07-05)*
- [ ] **#6** - RenderTexture concept for all UIDrawables - *Extensive Overhaul*
- [x] **#47** - New README.md for Alpha release - *Completed*
- [x] **#3** - Remove deprecated `McRFPy_API::player_input` - *Completed*
- [x] **#2** - Remove `registerPyAction` system - *Completed*

---

## 🗂 ISSUE TRIAGE BY SYSTEM (78 Total Issues)

### 🎮 Core Engine Systems

#### Iterator/Collection System (2 issues)
- [x] **#73** - Entity index() method for removal - *Fixed*
- [x] **#69** ⚠️ **Alpha Blocker** - Sequence Protocol refactor - *Completed! (2025-07-05)*

#### 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*
- [x] **#59** ⚠️ **Alpha Blocker** - Animation system - *Completed! (2025-07-05)*  
- [ ] **#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*
- [x] **#33** - Sprite index validation against texture range - *Fixed*

#### 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*  
- [x] **#27** - UIEntityCollection.extend() method - *Fixed*
- [ ] **#28** - UICollectionIter for scene ui iteration - *Isolated Fix*
- [ ] **#26** - UIEntityCollectionIter implementation - *Isolated Fix*

### 🧹 Refactoring & Cleanup

#### Code Cleanup (7 issues)
- [x] **#3** ⚠️ **Alpha Blocker** - Remove `McRFPy_API::player_input` - *Completed*
- [x] **#2** ⚠️ **Alpha Blocker** - Review `registerPyAction` necessity - *Completed*
- [ ] **#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) - COMPLETE! 30+ easing functions, all UI properties
5. ✅ Documentation (#47) - README.md complete, #48 dependency docs remaining
```

### 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 Alpha Blocker issues resolved (5 of 7 complete: #69, #59, #47, #3, #2)
- [ ] 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-05*  
*Total Open Issues: 62* (from original 78)  
*Alpha Blockers: 2* (was 7 - completed #69 Sequence Protocol, #59 Animation, #63 Z-order, #47 README, #3/#2 deprecated methods)  
*Current Work: Python Sequence Protocol complete! Full collection behavior with slicing, operators, and type safety*  
*Next Session: RenderTexture concept (#6) - Last major alpha blocker!*