From bde82028b58543f79f92ecf59ba6f119aedbdc4a Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sat, 12 Jul 2025 14:42:43 -0400 Subject: [PATCH] Roadmap: Integrate July 12 transcript analysis - critical tutorial blockers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit URGENT: RoguelikeDev event starts July 15 (3 days) Critical Blockers Identified: - Animation system blocking tutorial Part 2 (input queueing, collision) - Grid clicking completely broken in headless mode - Python API consistency issues found during tutorial writing - Object splitting bug: derived classes lose type in collections Added Sections: - Detailed tutorial status with specific blockers - Animation system critical issues breakdown - Grid clicking discovery (all events commented out) - Python API consistency crisis details - Proposed architecture improvements (OOP overhaul) - Claude Code quality concerns after 6-7 weeks - Comprehensive 34-issue list from transcript analysis Immediate Actions Required: 1. Fix animation input queueing TODAY 2. Fix grid clicking implementation TODAY 3. Create tutorial announcement if blockers fixed 4. Regenerate Parts 3-6 (machine drafts broken) ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- ROADMAP.md | 935 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 935 insertions(+) create mode 100644 ROADMAP.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..27a8ed5 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,935 @@ +# McRogueFace - Development Roadmap + +## ๐Ÿšจ URGENT PRIORITIES - July 12, 2025 ๐Ÿšจ + +### CRITICAL: RoguelikeDev Tutorial Event starts July 15! (3 days) + +#### 1. Tutorial Status & Blockers +- [x] **Part 0**: Complete (Starting McRogueFace) +- [x] **Part 1**: Complete (Setting up grid and tile sheet) +- [ ] **Part 2**: Draft exists but BLOCKED by animation issues - PRIORITY FIX! +- [ ] **Parts 3-6**: Machine-generated drafts need complete rework +- [ ] **Parts 7-15**: Need creation this weekend + +**Key Blockers**: +- Need smooth character movement animation (Pokemon-style) +- Grid needs walkable grass center, non-walkable tree edges +- Input queueing during animations not working properly + +#### 2. Animation System Critical Issues ๐Ÿšจ +**BLOCKER FOR TUTORIAL PART 2**: +- [ ] **Input Queue System**: Holding arrow keys doesn't queue movements + - Animation must complete before next input accepted + - Need "press and hold" that queues ONE additional move + - Goal: Pokemon-style smooth continuous movement +- [ ] **Collision Reservation**: When entity starts moving, should block destination + - Prevents overlapping movements + - Already claimed tiles should reject incoming entities +- [x] **Segfault Fix**: Refactored from bare pointers to weak references โœ… + +#### 3. Grid Clicking BROKEN in Headless Mode ๐Ÿšจ +**MAJOR DISCOVERY**: All click events commented out! +- [ ] **Automation System Non-Functional**: Claude Code "didn't even try" +- [ ] **Grid Click Coordinates**: Need tile coords, not just mouse coords +- [ ] **Nested Grid Support**: Clicks must work on grids within frames +- [ ] **No Error Reporting**: System claimed complete but isn't + +#### 4. Python API Consistency Crisis +**Tutorial Writing Reveals Major Issues**: +- [ ] **Inconsistent Constructors**: Each class has different requirements +- [ ] **Vector Class Broken**: No [0], [1] indexing like tuples +- [ ] **Object Splitting Bug**: Python derived classes lose type in collections + - Shared pointer extracted, Python reference discarded + - Retrieved objects are base class only + - No way to cast back to derived type +- [ ] **Need Systematic Generation**: All bindings should be consistent +- [x] **UIGrid TCOD Integration** (8 hours) โœ… COMPLETED! + - โœ… Add TCODMap* to UIGrid constructor with proper lifecycle + - โœ… Implement complete Dijkstra pathfinding system + - โœ… Create mcrfpy.libtcod submodule with Python bindings + - โœ… Fix critical PyArg bug preventing Color object assignments + - โœ… Implement FOV with perspective rendering + - [ ] Add batch operations for NumPy-style access (deferred) + - [ ] Create CellView for ergonomic .at((x,y)) access (deferred) +- [x] **UIEntity Pathfinding** (4 hours) โœ… COMPLETED! + - โœ… Implement Dijkstra maps for multiple targets in UIGrid + - โœ… Add path_to(target) method using A* to UIEntity + - โœ… Cache paths in UIEntity for performance + +#### 3. Performance Critical Path +- [ ] **Implement SpatialHash** for 10,000+ entities (2 hours) +- [ ] **Add dirty flag system** to UIGrid (1 hour) +- [ ] **Batch update context managers** (2 hours) +- [ ] **Memory pool for entities** (2 hours) + +#### 4. Bug Fixing Pipeline +- [ ] Set up GitHub Issues automation +- [ ] Create test for each bug before fixing +- [ ] Track: Memory leaks, Segfaults, Python/C++ boundary errors + +--- + +## ๐Ÿ—๏ธ PROPOSED ARCHITECTURE IMPROVEMENTS (From July 12 Analysis) + +### Object-Oriented Design Overhaul +1. **Scene System Revolution**: + - [ ] Make Scene derive from Drawable (scenes are drawn!) + - [ ] Give scenes position and visibility properties + - [ ] Scene selection by visibility (auto-hide old scene) + - [ ] Replace transition system with animations + +2. **Animation System Enhancements**: + - [ ] Add proper completion callbacks (object + animation params) + - [ ] Prevent property conflicts (exclusive locking) + - [ ] Currently using timer sync workarounds + +3. **Timer System Improvements**: + - [ ] Replace string-dictionary system with objects + - [ ] Add start(), stop(), pause() methods + - [ ] Implement proper one-shot mode + - [ ] Pass timer object to callbacks (not just ms) + +4. **Parent-Child UI Relationships**: + - [ ] Add parent field to UI drawables (like entities have) + - [ ] Implement append/remove/extend with auto-parent updates + - [ ] Auto-remove from old parent when adding to new + +### Performance Optimizations Needed +- [ ] **Grid Rendering**: Consider texture caching vs real-time +- [ ] **Subgrid System**: Split large grids into 256x256 chunks +- [ ] **Dirty Flagging**: Propagate from base class up +- [ ] **Animation Features**: Tile color animation, sprite cycling + +--- + +## โš ๏ธ CLAUDE CODE QUALITY CONCERNS (6-7 Weeks In) + +### Issues Observed: +1. **Declining Quality**: High quantity but low quality results +2. **Not Following Requirements**: Ignoring specific implementation needs +3. **Bad Practices**: + - Creating parallel copies (animation_RAII.cpp, _fixed, _final versions) + - Should use Git, not file copies + - Claims functionality "done" when stubbed out +4. **File Management Problems**: + - Git operations reset timestamps + - Can't determine creation order of multiple versions + +### Recommendations: +- Use Git for version control exclusively +- Fix things in place, not copies +- Acknowledge incomplete functionality +- Follow project's implementation style + +--- + +## ๐ŸŽฏ STRATEGIC ARCHITECTURE VISION + +### Three-Layer Grid Architecture (From Compass Research) +Following successful roguelike patterns (Caves of Qud, Cogmind, DCSS): + +1. **Visual Layer** (UIGridPoint) - Sprites, colors, animations +2. **World State Layer** (TCODMap) - Walkability, transparency, physics +3. **Entity Perspective Layer** (UIGridPointState) - Per-entity FOV, knowledge + +### Performance Architecture (Critical for 1000x1000 maps) +- **Spatial Hashing** for entity queries (not quadtrees!) +- **Batch Operations** with context managers (10-100x speedup) +- **Memory Pooling** for entities and components +- **Dirty Flag System** to avoid unnecessary updates +- **Zero-Copy NumPy Integration** via buffer protocol + +### Key Insight from Research +"Minimizing Python/C++ boundary crossings matters more than individual function complexity" +- Batch everything possible +- Use context managers for logical operations +- Expose arrays, not individual cells +- Profile and optimize hot paths only + +--- + +## Project Status: ๐ŸŽ‰ ALPHA 0.1 RELEASE! ๐ŸŽ‰ + +**Current State**: Documentation system complete, TCOD integration urgent +**Latest Update**: Tutorial Parts 0-6 complete with documentation (2025-07-11) +**Branch**: alpha_streamline_2 +**Open Issues**: ~46 remaining + URGENT TCOD/Tutorial work + +--- + +## ๐Ÿ“‹ TCOD Integration Implementation Details + +### Phase 1: Core UIGrid Integration (Day 1 Morning) +```cpp +// UIGrid.h additions +class UIGrid : public UIDrawable { +private: + TCODMap* world_state; // Add TCOD map + std::unordered_map entity_perspectives; + bool batch_mode = false; + std::vector pending_updates; +``` + +### Phase 2: Python Bindings (Day 1 Afternoon) +```python +# New API surface +grid = mcrfpy.Grid(100, 100) +grid.compute_fov(player.x, player.y, radius=10) # Returns visible cells +grid.at((x, y)).walkable = False # Ergonomic access +with grid.batch_update(): # Context manager for performance + # All updates batched +``` + +### Phase 3: Entity Integration (Day 2 Morning) +```python +# UIEntity additions +entity.path_to(target_x, target_y) # A* pathfinding +entity.flee_from(threat) # Dijkstra map +entity.can_see(other_entity) # FOV check +``` + +### Critical Success Factors: +1. **Batch everything** - Never update single cells in loops +2. **Lazy evaluation** - Only compute FOV for entities that need it +3. **Sparse storage** - Don't store full grids per entity +4. **Profile early** - Find the 20% of code taking 80% of time + +--- + +## Recent Achievements + +### 2025-07-12: Animation System RAII Overhaul - Critical Segfault Fix! ๐Ÿ›ก๏ธ +**Fixed two major crashes in AnimationManager** +- โœ… Race condition when creating animations in timer callbacks +- โœ… Exit crash when animations outlive their targets +- โœ… Implemented weak_ptr tracking for automatic cleanup +- โœ… Added complete() and hasValidTarget() methods +- โœ… No more use-after-free bugs - proper RAII design +- โœ… Extensively tested with stress tests and production demos + +### 2025-07-10: Complete FOV, A* Pathfinding & GUI Text Widgets! ๐Ÿ‘๏ธ๐Ÿ—บ๏ธโŒจ๏ธ +**Engine Feature Sprint - Major Capabilities Added** +- โœ… Complete FOV (Field of View) system with perspective rendering + - UIGrid.perspective property controls which entity's view to render + - Three-layer overlay system: unexplored (black), explored (dark), visible (normal) + - Per-entity visibility state tracking with UIGridPointState + - Perfect knowledge updates - only explored areas persist +- โœ… A* Pathfinding implementation + - Entity.path_to(x, y) method for direct pathfinding + - UIGrid compute_astar() and get_astar_path() methods + - Path caching in entities for performance + - Complete test suite comparing A* vs Dijkstra performance +- โœ… GUI Text Input Widget System + - Full-featured TextInputWidget class with cursor, selection, scrolling + - Improved widget with proper text rendering and multi-line support + - Example showcase demonstrating multiple input fields + - Foundation for in-game consoles, chat systems, and text entry +- โœ… Sizzle Reel Demos + - path_vision_sizzle_reel.py combines pathfinding with FOV + - Interactive visibility demos showing real-time FOV updates + - Performance demonstrations with multiple entities + +### 2025-07-09: Dijkstra Pathfinding & Critical Bug Fix! ๐Ÿ—บ๏ธ +**TCOD Integration Sprint - Major Progress** +- โœ… Complete Dijkstra pathfinding implementation in UIGrid + - compute_dijkstra(), get_dijkstra_distance(), get_dijkstra_path() methods + - Full TCODMap and TCODDijkstra integration with proper memory management + - Comprehensive test suite with both headless and interactive demos +- โœ… **CRITICAL FIX**: PyArg bug in UIGridPoint color setter + - Now supports both mcrfpy.Color objects and (r,g,b,a) tuples + - Eliminated mysterious "SystemError: new style getargs format" crashes + - Proper error handling and exception propagation +- โœ… mcrfpy.libtcod submodule with Python bindings + - dijkstra_compute(), dijkstra_get_distance(), dijkstra_get_path() + - line() function for corridor generation + - Foundation ready for FOV implementation +- โœ… Test consolidation: 6 broken demos โ†’ 2 clean, working versions + +### 2025-07-08: PyArgHelpers Infrastructure Complete! ๐Ÿ”ง +**Standardized Python API Argument Parsing** +- Unified position handling: (x, y) tuples or separate x, y args +- Consistent size parsing: (w, h) tuples or width, height args +- Grid-specific helpers for tile-based positioning +- Proper conflict detection between positional and keyword args +- All UI components migrated: Frame, Caption, Sprite, Grid, Entity +- Improved error messages: "Value must be a number (int or float)" +- Foundation for Phase 7 documentation efforts + +### 2025-07-05: ALPHA 0.1 ACHIEVED! ๐ŸŽŠ๐Ÿพ +**All Alpha Blockers Resolved!** +- Z-order rendering with performance optimization (Issue #63) +- Python Sequence Protocol for collections (Issue #69) +- Comprehensive Animation System (Issue #59) +- Moved RenderTexture to Beta (not needed for Alpha) +- **McRogueFace is ready for Alpha release!** + +### 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: Alpha Streamline 2 - Major Architecture Improvements + +### Recent Completions: +- โœ… **Phase 1-4 Complete** - Foundation, API Polish, Entity Lifecycle, Visibility/Performance +- โœ… **Phase 5 Complete** - Window/Scene Architecture fully implemented! + - Window singleton with properties (#34) + - OOP Scene support with lifecycle methods (#61) + - Window resize events (#1) + - Scene transitions with animations (#105) +- โœ… **Phase 6 Complete** - Rendering Revolution achieved! + - Grid background colors (#50) โœ… + - RenderTexture overhaul (#6) โœ… + - UIFrame clipping support โœ… + - Viewport-based rendering (#8) โœ… + +### Active Development: +- **Branch**: alpha_streamline_2 +- **Current Phase**: Phase 7 - Documentation & Distribution +- **Achievement**: PyArgHelpers infrastructure complete - standardized Python API +- **Strategic Vision**: See STRATEGIC_VISION.md for platform roadmap +- **Latest**: All UI components now use consistent argument parsing patterns! + +### ๐Ÿ—๏ธ Architectural Dependencies Map + +``` +Foundation Layer: +โ”œโ”€โ”€ #71 Base Class (_Drawable) +โ”‚ โ”œโ”€โ”€ #10 Visibility System (needs AABB from base) +โ”‚ โ”œโ”€โ”€ #87 visible property +โ”‚ โ””โ”€โ”€ #88 opacity property +โ”‚ +โ”œโ”€โ”€ #7 Safe Constructors (affects all classes) +โ”‚ โ””โ”€โ”€ Blocks any new class creation until resolved +โ”‚ +โ””โ”€โ”€ #30 Entity/Grid Integration (lifecycle management) + โ””โ”€โ”€ Enables reliable entity management + +Window/Scene Layer: +โ”œโ”€โ”€ #34 Window Object +โ”‚ โ”œโ”€โ”€ #61 Scene Object (depends on Window) +โ”‚ โ”œโ”€โ”€ #14 SFML Exposure (helps implement Window) +โ”‚ โ””โ”€โ”€ Future: Multi-window support + +Rendering Layer: +โ””โ”€โ”€ #6 RenderTexture Overhaul + โ”œโ”€โ”€ Enables clipping + โ”œโ”€โ”€ Off-screen rendering + โ””โ”€โ”€ Post-processing effects +``` + +## ๐Ÿš€ Alpha Streamline 2 - Comprehensive Phase Plan + +### Phase 1: Foundation Stabilization (1-2 weeks) +**Goal**: Safe, predictable base for all future work +``` +1. #7 - Audit and fix unsafe constructors (CRITICAL - do first!) + - Find all manually implemented no-arg constructors + - Verify map compatibility requirements + - Make pointer-safe or remove + +2. #71 - _Drawable base class implementation + - Common properties: x, y, w, h, visible, opacity + - Virtual methods: get_bounds(), render() + - Proper Python inheritance setup + +3. #87 - visible property + - Add to base class + - Update all render methods to check + +4. #88 - opacity property (depends on #87) + - 0.0-1.0 float range + - Apply in render methods + +5. #89 - get_bounds() method + - Virtual method returning (x, y, w, h) + - Override in each UI class + +6. #98 - move()/resize() convenience methods + - move(dx, dy) - relative movement + - resize(w, h) - absolute sizing +``` +*Rationale*: Can't build on unsafe foundations. Base class enables all UI improvements. + +### Phase 2: Constructor & API Polish (1 week) +**Goal**: Pythonic, intuitive API +``` +1. #101 - Standardize (0,0) defaults for all positions +2. #38 - Frame children parameter: Frame(children=[...]) +3. #42 - Click handler in __init__: Button(click=callback) +4. #90 - Grid size tuple: Grid(grid_size=(10, 10)) +5. #19 - Sprite texture swapping: sprite.texture = new_texture +6. #52 - Grid skip out-of-bounds entities (performance) +``` +*Rationale*: Quick wins that make the API more pleasant before bigger changes. + +### Phase 3: Entity Lifecycle Management (1 week) +**Goal**: Bulletproof entity/grid relationships +``` +1. #30 - Entity.die() and grid association + - Grid.entities.append(e) sets e.grid = self + - Grid.entities.remove(e) sets e.grid = None + - Entity.die() calls self.grid.remove(self) + - Entity can only be in 0 or 1 grid + +2. #93 - Vector arithmetic methods + - add, subtract, multiply, divide + - distance, normalize, dot product + +3. #94 - Color helper methods + - from_hex("#FF0000"), to_hex() + - lerp(other_color, t) for interpolation + +4. #103 - Timer objects + timer = mcrfpy.Timer("my_timer", callback, 1000) + timer.pause() + timer.resume() + timer.cancel() +``` +*Rationale*: Games need reliable entity management. Timer objects enable entity AI. + +### Phase 4: Visibility & Performance (1-2 weeks) +**Goal**: Only render/process what's needed +``` +1. #10 - [UNSCHEDULED] Full visibility system with AABB + - Postponed: UIDrawables can exist in multiple collections + - Cannot reliably determine screen position due to multiple render contexts + - Needs architectural solution for parent-child relationships + +2. #52 - Grid culling (COMPLETED in Phase 2) + +3. #39/40/41 - Name system for finding elements + - name="button1" property on all UIDrawables + - only_one=True for unique names + - scene.find("button1") returns element + - collection.find("enemy*") returns list + +4. #104 - Basic profiling/metrics + - Frame time tracking + - Draw call counting + - Python vs C++ time split +``` +*Rationale*: Performance is feature. Finding elements by name is huge QoL. + +### Phase 5: Window/Scene Architecture โœ… COMPLETE! (2025-07-06) +**Goal**: Modern, flexible architecture +``` +1. โœ… #34 - Window object (singleton first) + window = mcrfpy.Window.get() + window.resolution = (1920, 1080) + window.fullscreen = True + window.vsync = True + +2. โœ… #1 - Window resize events + scene.on_resize(self, width, height) callback implemented + +3. โœ… #61 - Scene object (OOP scenes) + class MenuScene(mcrfpy.Scene): + def on_keypress(self, key, state): + # handle input + def on_enter(self): + # setup UI + def on_exit(self): + # cleanup + def update(self, dt): + # frame update + +4. โœ… #14 - SFML exposure research + - Completed comprehensive analysis + - Recommendation: Direct integration as mcrfpy.sfml + - SFML 3.0 migration deferred to late 2025 + +5. โœ… #105 - Scene transitions + mcrfpy.setScene("menu", "fade", 1.0) + # Supports: fade, slide_left, slide_right, slide_up, slide_down +``` +*Result*: Entire window/scene system modernized with OOP design! + +### Phase 6: Rendering Revolution (3-4 weeks) โœ… COMPLETE! +**Goal**: Professional rendering capabilities +``` +1. โœ… #50 - Grid background colors [COMPLETED] + grid.background_color = mcrfpy.Color(50, 50, 50) + - Added background_color property with animation support + - Default dark gray background (8, 8, 8, 255) + +2. โœ… #6 - RenderTexture overhaul [COMPLETED] + โœ… Base infrastructure in UIDrawable + โœ… UIFrame clip_children property + โœ… Dirty flag optimization system + โœ… Nested clipping support + โœ… UIGrid already has appropriate RenderTexture implementation + โŒ UICaption/UISprite clipping not needed (no children) + +3. โœ… #8 - Viewport-based rendering [COMPLETED] + - Fixed game resolution (window.game_resolution) + - Three scaling modes: "center", "stretch", "fit" + - Window to game coordinate transformation + - Mouse input properly scaled with windowToGameCoords() + - Python API fully integrated + - Tests: test_viewport_simple.py, test_viewport_visual.py, test_viewport_scaling.py + +4. #106 - Shader support [DEFERRED TO POST-PHASE 7] + sprite.shader = mcrfpy.Shader.load("glow.frag") + frame.shader_params = {"intensity": 0.5} + +5. #107 - Particle system [DEFERRED TO POST-PHASE 7] + emitter = mcrfpy.ParticleEmitter() + emitter.texture = spark_texture + emitter.emission_rate = 100 + emitter.lifetime = (0.5, 2.0) +``` + +**Phase 6 Achievement Summary**: +- Grid backgrounds (#50) โœ… - Customizable background colors with animation +- RenderTexture overhaul (#6) โœ… - UIFrame clipping with opt-in architecture +- Viewport rendering (#8) โœ… - Three scaling modes with coordinate transformation +- UIGrid already had optimal RenderTexture implementation for its use case +- UICaption/UISprite clipping unnecessary (no children to clip) +- Performance optimized with dirty flag system +- Backward compatibility preserved throughout +- Effects/Shader/Particle systems deferred for focused delivery + +*Rationale*: This unlocks professional visual effects but is complex. + +### Phase 7: Documentation & Distribution (1-2 weeks) +**Goal**: Ready for the world +``` +1. โœ… #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08] +2. โœ… #86 - Add parameter documentation [COMPLETED 2025-07-08] +3. โœ… #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08] +4. โŒ #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch] +5. API reference generator tool +``` + +## ๐Ÿ“‹ Critical Path & Parallel Tracks + +### ๐Ÿ”ด **Critical Path** (Must do in order) +**Safe Constructors (#7)** โ†’ **Base Class (#71)** โ†’ **Visibility (#10)** โ†’ **Window (#34)** โ†’ **Scene (#61)** + +### ๐ŸŸก **Parallel Tracks** (Can be done alongside critical path) + +**Track A: Entity Systems** +- Entity/Grid integration (#30) +- Timer objects (#103) +- Vector/Color helpers (#93, #94) + +**Track B: API Polish** +- Constructor improvements (#101, #38, #42, #90) +- Sprite texture swap (#19) +- Name/search system (#39/40/41) + +**Track C: Performance** +- Grid culling (#52) +- Visibility culling (part of #10) +- Profiling tools (#104) + +### ๐Ÿ’Ž **Quick Wins to Sprinkle Throughout** +1. Color helpers (#94) - 1 hour +2. Vector methods (#93) - 1 hour +3. Grid backgrounds (#50) - 30 minutes +4. Default positions (#101) - 30 minutes + +### ๐ŸŽฏ **Recommended Execution Order** + +**Week 1-2**: Foundation (Critical constructors + base class) +**Week 3**: Entity lifecycle + API polish +**Week 4**: Visibility system + performance +**Week 5-6**: Window/Scene architecture +**Week 7-9**: Rendering revolution (or defer to gamma) +**Week 10**: Documentation + release prep + +### ๐Ÿ†• **New Issues to Create/Track** + +1. [x] **Timer Objects** - Pythonic timer management (#103) - *Completed Phase 3* +2. [ ] **Event System Enhancement** - Mouse enter/leave, drag, right-click +3. [ ] **Resource Manager** - Centralized asset loading +4. [ ] **Serialization System** - Save/load game state +5. [x] **Scene Transitions** - Fade, slide, custom effects (#105) - *Completed Phase 5* +6. [x] **Profiling Tools** - Performance metrics (#104) - *Completed Phase 4* +7. [ ] **Particle System** - Visual effects framework (#107) +8. [ ] **Shader Support** - Custom rendering effects (#106) + +--- + +## ๐Ÿ“‹ Phase 6 Implementation Strategy + +### RenderTexture Overhaul (#6) - Technical Approach + +**Current State**: +- UIGrid already uses RenderTexture for entity rendering +- Scene transitions use RenderTextures for smooth animations +- Direct rendering to window for Frame, Caption, Sprite + +**Implementation Plan**: +1. **Base Infrastructure**: + - Add `sf::RenderTexture* target` to UIDrawable base + - Modify `render()` to check if target exists + - If target: render to texture, then draw texture to parent + - If no target: render directly (backward compatible) + +2. **Clipping Support**: + - Frame enforces bounds on children via RenderTexture + - Children outside bounds are automatically clipped + - Nested frames create render texture hierarchy + +3. **Performance Optimization**: + - Lazy RenderTexture creation (only when needed) + - Dirty flag system (only re-render when changed) + - Texture pooling for commonly used sizes + +4. **Integration Points**: + - Scene transitions already working with RenderTextures + - UIGrid can be reference implementation + - Test with deeply nested UI structures + +**Quick Wins Before Core Work**: +1. **Grid Background (#50)** - 30 min implementation + - Add `background_color` and `background_texture` properties + - Render before entities in UIGrid::render() + - Good warm-up before tackling RenderTexture + +2. **Research Tasks**: + - Study UIGrid's current RenderTexture usage + - Profile scene transition performance + - Identify potential texture size limits + +--- + +## ๐Ÿš€ NEXT PHASE: Beta Features & Polish + +### Alpha Complete! Moving to Beta Priorities: +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* + Issue #37 is **on hold** until we have a Windows build environment available. I actually suspect this is already fixed by the updates to the makefile, anyway. +- [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 + +--- + +## ๐Ÿ—‚ 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) +- [x] **#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 - *Research Complete, Implementation Pending* +- [ ] **#46** - Subinterpreter threading tests - *Multiple Integrations* + +#### UI/Rendering System (12 issues) +- [x] **#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* +- [x] **#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* +- [x] **#12** - GridPoint/GridPointState forbid direct init - *Isolated Fix* + +#### Scene/Window Management (5 issues) +- [x] **#61** - Scene object encapsulating key callbacks - *Completed Phase 5* +- [x] **#34** - Window object for resolution/scaling - *Completed Phase 5* +- [ ] **#62** - Multiple windows support - *Extensive Overhaul* +- [ ] **#49** - Window resolution & viewport controls - *Multiple Integrations* +- [x] **#1** - Scene resize event handling - *Completed Phase 5* + +### ๐Ÿ”ง 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) +- [x] **#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* + +--- + +## ๐ŸŽฎ 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 + +--- + +## ๐Ÿ“š 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) + +--- + +## ๐Ÿ”ฎ FUTURE VISION: Pure Python Extension Architecture + +### Concept: McRogueFace as a Traditional Python Package +**Status**: Unscheduled - Long-term vision +**Complexity**: Major architectural overhaul + +Instead of being a C++ application that embeds Python, McRogueFace could be redesigned as a pure Python extension module that can be installed via `pip install mcrogueface`. + +### Technical Approach +1. **Separate Core Engine from Python Embedding** + - Extract SFML rendering, audio, and input into C++ extension modules + - Remove embedded CPython interpreter + - Use Python's C API to expose functionality + +2. **Module Structure** + ``` + mcrfpy/ + โ”œโ”€โ”€ __init__.py # Pure Python coordinator + โ”œโ”€โ”€ _core.so # C++ rendering/game loop extension + โ”œโ”€โ”€ _sfml.so # SFML bindings + โ”œโ”€โ”€ _audio.so # Audio system bindings + โ””โ”€โ”€ engine.py # Python game engine logic + ``` + +3. **Inverted Control Flow** + - Python drives the main loop instead of C++ + - C++ extensions handle performance-critical operations + - Python manages game logic, scenes, and entity systems + +### Benefits +- **Standard Python Packaging**: `pip install mcrogueface` +- **Virtual Environment Support**: Works with venv, conda, poetry +- **Better IDE Integration**: Standard Python development workflow +- **Easier Testing**: Use pytest, standard Python testing tools +- **Cross-Python Compatibility**: Support multiple Python versions +- **Modular Architecture**: Users can import only what they need + +### Challenges +- **Major Refactoring**: Complete restructure of codebase +- **Performance Considerations**: Python-driven main loop overhead +- **Build Complexity**: Multiple extension modules to compile +- **Platform Support**: Need wheels for many platform/Python combinations +- **API Stability**: Would need careful design to maintain compatibility + +### Implementation Phases (If Pursued) +1. **Proof of Concept**: Simple SFML binding as Python extension +2. **Core Extraction**: Separate rendering from Python embedding +3. **Module Design**: Define clean API boundaries +4. **Incremental Migration**: Move systems one at a time +5. **Compatibility Layer**: Support existing games during transition + +### Example Usage (Future Vision) +```python +import mcrfpy +from mcrfpy import Scene, Frame, Sprite, Grid + +# Create game directly in Python +game = mcrfpy.Game(width=1024, height=768) + +# Define scenes using Python classes +class MainMenu(Scene): + def on_enter(self): + self.ui.append(Frame(100, 100, 200, 50)) + self.ui.append(Sprite("logo.png", x=400, y=100)) + + def on_keypress(self, key, pressed): + if key == "ENTER" and pressed: + self.game.set_scene("game") + +# Run the game +game.add_scene("menu", MainMenu()) +game.run() +``` + +This architecture would make McRogueFace a first-class Python citizen, following standard Python packaging conventions while maintaining high performance through C++ extensions. + +--- + +## ๐Ÿš€ IMMEDIATE NEXT STEPS (Priority Order) + +### TODAY (July 12) - CRITICAL PATH: +1. **FIX ANIMATION BLOCKERS** for Tutorial Part 2: + - Implement input queueing during animations + - Add destination square reservation + - Test Pokemon-style continuous movement +2. **FIX GRID CLICKING** (discovered broken in headless): + - Uncomment and implement click events + - Add tile coordinate conversion + - Enable nested grid support +3. **CREATE TUTORIAL ANNOUNCEMENT** if blockers fixed + +### Weekend (July 13-14) - Tutorial Sprint: +1. **Regenerate Parts 3-6** (machine drafts are broken) +2. **Create Parts 7-10**: Interface, Items, Targeting, Save/Load +3. **Create Parts 11-15**: Dungeon levels, difficulty, equipment +4. **Post more frequently during event** (narrator emphasis) + +### Architecture Decision Log: +- **DECIDED**: Use three-layer architecture (visual/world/perspective) +- **DECIDED**: Spatial hashing over quadtrees for entities +- **DECIDED**: Batch operations are mandatory, not optional +- **DECIDED**: TCOD integration as mcrfpy.libtcod submodule +- **DECIDED**: Tutorial must showcase McRogueFace strengths, not mimic TCOD + +### Risk Mitigation: +- **If TCOD integration delays**: Use pure Python FOV for tutorial +- **If performance issues**: Focus on <100x100 maps for demos +- **If tutorial incomplete**: Ship with 4 solid parts + roadmap +- **If bugs block progress**: Document as "known issues" and continue + +--- + +## ๐Ÿ“‹ COMPREHENSIVE ISSUES FROM TRANSCRIPT ANALYSIS + +### Animation System (6 issues) +1. **Input Queue During Animation**: Queue one additional move during animation +2. **Destination Square Reservation**: Block target when movement begins +3. **Pokemon-Style Movement**: Smooth continuous movement with input handling +4. **Animation Callbacks**: Add completion callbacks with parameters +5. **Property Conflict Prevention**: Prevent multiple animations on same property +6. **Remove Bare Pointers**: Complete refactoring to weak references โœ… + +### Grid System (6 issues) +7. **Grid Click Implementation**: Fix commented-out events in headless +8. **Tile Coordinate Conversion**: Convert mouse to tile coordinates +9. **Nested Grid Support**: Enable clicking on grids within grids +10. **Grid Rendering Performance**: Implement 256x256 subgrid system +11. **Dirty Flagging**: Add dirty flag propagation from base +12. **Grid Point Animation**: Enable animating individual tiles + +### Python API (6 issues) +13. **Regenerate Python Bindings**: Create consistent interface generation +14. **Vector Class Enhancement**: Add [0], [1] indexing to vectors +15. **Fix Object Splitting**: Preserve Python derived class types +16. **Standardize Constructors**: Make all constructors consistent +17. **Color Class Bindings**: Properly expose SFML Color class +18. **Font Class Bindings**: Properly expose SFML Font class + +### Architecture (8 issues) +19. **Scene as Drawable**: Refactor Scene to inherit from Drawable +20. **Scene Visibility System**: Implement exclusive visibility switching +21. **Replace Transition System**: Use animations not special transitions +22. **Parent-Child UI**: Add parent field to UI drawables +23. **Collection Methods**: Implement append/remove/extend with parent updates +24. **Timer Object System**: Replace string-dictionary timers +25. **One-Shot Timer Mode**: Implement proper one-shot functionality +26. **Button Mechanics**: Any entity type can trigger buttons + +### Entity System (4 issues) +27. **Step-On Entities**: Implement trigger when stepped on +28. **Bump Interaction**: Add bump-to-interact behavior +29. **Type-Aware Interactions**: Entity interactions based on type +30. **Button Mechanics**: Any entity can trigger buttons + +### Tutorial & Documentation (4 issues) +31. **Fix Part 2 Tutorial**: Unblock with animation fixes +32. **Regenerate Parts 3-6**: Replace machine-generated content +33. **API Documentation**: Document ergonomic improvements +34. **Tutorial Alignment**: Ensure parts match TCOD structure + +--- + +*Last Updated: 2025-07-12 (CRITICAL TUTORIAL SPRINT)* +*Next Review: July 15 after event start*