John McCardle
923350137d
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().
312 lines
14 KiB
Markdown
312 lines
14 KiB
Markdown
# 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*
|
|
|