# McRogueFace - Development Roadmap ## ๐Ÿšจ URGENT PRIORITIES - July 9, 2025 ๐Ÿšจ ### IMMEDIATE ACTION REQUIRED (Next 48 Hours) **CRITICAL DEADLINE**: RoguelikeDev Tutorial Event starts July 15 - Need to advertise by July 11! #### 1. Tutorial Emergency Plan (2 DAYS) - [ ] **Day 1 (July 9)**: Parts 1-2 (Setup, Moving @, Drawing Map, Entities) - [ ] **Day 2 (July 10)**: Parts 3-4 (FOV, Combat/AI) - [ ] **July 11**: Announce on r/roguelikedev with 4 completed parts - [ ] **July 12-14**: Complete remaining 10 parts before event starts #### 1b. Sizzle Reel Demo (URGENT) - [ ] **Expand animation_sizzle_reel_working.py** with Grid/Entity demos: - Grid scrolling and zooming animations - Entity movement patterns (patrol, chase, flee) - Particle effects using entity spawning - Tile animation demonstrations - Color cycling and transparency effects - Mass entity choreography (100+ entities) - Performance stress test with 1000+ entities #### 2. TCOD Integration Sprint - [ ] **UIGrid TCOD Integration** (8 hours) - Add TCODMap* to UIGrid constructor - Implement mcrfpy.libtcod.compute_fov() - Add batch operations for NumPy-style access - Create CellView for ergonomic .at((x,y)) access - [ ] **UIEntity Pathfinding** (4 hours) - Add path_to(target) method using A* - Implement Dijkstra maps for multiple targets - 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 --- ## ๐ŸŽฏ 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**: Completed Phase 7 documentation infrastructure (2025-07-08) **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-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 9) - EXECUTE NOW: 1. **Start Tutorial Part 1** - Basic setup and @ movement (2 hours) 2. **Implement UIGrid.at((x,y))** - CellView pattern (1 hour) 3. **Create Grid demo** for sizzle reel (1 hour) 4. **Fix any blocking bugs** discovered during tutorial writing ### Tomorrow (July 10) - CRITICAL PATH: 1. **Tutorial Parts 2-4** - Map drawing, entities, FOV, combat 2. **Implement compute_fov()** in UIGrid 3. **Add batch_update context manager** 4. **Expand sizzle reel** with entity choreography ### July 11 - ANNOUNCEMENT DAY: 1. **Polish 4 tutorial parts** 2. **Create announcement post** for r/roguelikedev 3. **Record sizzle reel video** 4. **Submit announcement** by end of day ### 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 --- *Last Updated: 2025-07-09 (URGENT SPRINT MODE)* *Next Review: July 11 after announcement*