39 KiB
McRogueFace - Development Roadmap
🚨 URGENT PRIORITIES - July 12, 2025 🚨
CRITICAL: RoguelikeDev Tutorial Event starts July 15! (3 days)
1. Tutorial Status & Blockers
- Part 0: Complete (Starting McRogueFace)
- 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
- Segfault Fix: Refactored from bare pointers to weak references ✅
3. Grid Clicking BROKEN in Headless Mode 🚨
MAJOR DISCOVERY: All click events commented out!
- #111 - Grid Click Events Broken in Headless: All click events commented out
- 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:
- #101/#110 - Inconsistent Constructors: Each class has different requirements
- #109 - Vector Class Broken: No [0], [1] indexing like tuples
- #112 - 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
- 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
- #113 - Add batch operations for NumPy-style access (deferred)
- #114 - Create CellView for ergonomic .at((x,y)) access (deferred)
- 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
- #115 - Implement SpatialHash for 10,000+ entities (2 hours)
- #116 - Add dirty flag system to UIGrid (1 hour)
- #113 - Batch update context managers (2 hours)
- #117 - Memory pool for entities (2 hours)
4. Bug Fixing Pipeline
- #125 - 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
-
Scene System Revolution:
- #118 - 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
-
Animation System Enhancements:
- #119 - Add proper completion callbacks (object + animation params)
- #120 - Prevent property conflicts (exclusive locking)
- Currently using timer sync workarounds
-
Timer System Improvements:
- #121 - Replace string-dictionary system with objects
- Add start(), stop(), pause() methods
- Implement proper one-shot mode
- Pass timer object to callbacks (not just ms)
-
Parent-Child UI Relationships:
- #122 - 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
- #123 - Subgrid System: Split large grids into 256x256 chunks
- #116 - Dirty Flagging: Propagate from base class up
- #124 - Animation Features: Tile color animation, sprite cycling
⚠️ CLAUDE CODE QUALITY CONCERNS (6-7 Weeks In)
Issues Observed:
- Declining Quality: High quantity but low quality results
- Not Following Requirements: Ignoring specific implementation needs
- Bad Practices:
- Creating parallel copies (animation_RAII.cpp, _fixed, _final versions)
- Should use Git, not file copies
- Claims functionality "done" when stubbed out
- 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):
- Visual Layer (UIGridPoint) - Sprites, colors, animations
- World State Layer (TCODMap) - Walkability, transparency, physics
- 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)
// UIGrid.h additions
class UIGrid : public UIDrawable {
private:
TCODMap* world_state; // Add TCOD map
std::unordered_map<int, UIGridPointState*> entity_perspectives;
bool batch_mode = false;
std::vector<CellUpdate> pending_updates;
Phase 2: Python Bindings (Day 1 Afternoon)
# 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)
# 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:
- Batch everything - Never update single cells in loops
- Lazy evaluation - Only compute FOV for entities that need it
- Sparse storage - Don't store full grids per entity
- 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
- Color helpers (#94) - 1 hour
- Vector methods (#93) - 1 hour
- Grid backgrounds (#50) - 30 minutes
- 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
- Timer Objects - Pythonic timer management (#103) - Completed Phase 3
- Event System Enhancement - Mouse enter/leave, drag, right-click
- Resource Manager - Centralized asset loading
- Serialization System - Save/load game state
- Scene Transitions - Fade, slide, custom effects (#105) - Completed Phase 5
- Profiling Tools - Performance metrics (#104) - Completed Phase 4
- Particle System - Visual effects framework (#107)
- 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:
-
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)
- Add
-
Clipping Support:
- Frame enforces bounds on children via RenderTexture
- Children outside bounds are automatically clipped
- Nested frames create render texture hierarchy
-
Performance Optimization:
- Lazy RenderTexture creation (only when needed)
- Dirty flag system (only re-render when changed)
- Texture pooling for commonly used sizes
-
Integration Points:
- Scene transitions already working with RenderTextures
- UIGrid can be reference implementation
- Test with deeply nested UI structures
Quick Wins Before Core Work:
-
Grid Background (#50) - 30 min implementation
- Add
background_color
andbackground_texture
properties - Render before entities in UIGrid::render()
- Good warm-up before tackling RenderTexture
- Add
-
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:
#69 - Python Sequence Protocol for collections- Completed! (2025-07-05)#63 - Z-order rendering for UIDrawables- Completed! (2025-07-05)#59 - Animation system- Completed! (2025-07-05)- #6 - RenderTexture concept - Extensive Overhaul
#47 - New README.md for Alpha release- Completed
- #78 - Middle Mouse Click sends "C" keyboard event - Fixed
- #77 - Fix error message copy/paste bug - Fixed
- #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.
- Entity Property Setters - Fix "new style getargs format" error - Fixed
- Sprite Texture Setter - Fix "error return without exception set" - Fixed
- 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
- #73 - Add
entity.index()
method for collection removal - Fixed - #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)
- #73 - Entity index() method for removal - Fixed
- #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 - Research Complete, Implementation Pending
- #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 - 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
- #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 - Completed Phase 5
- #34 - Window object for resolution/scaling - Completed Phase 5
- #62 - Multiple windows support - Extensive Overhaul
- #49 - Window resolution & viewport controls - Multiple Integrations
- #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
- #27 - UIEntityCollection.extend() method - Fixed
- #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
- Completed - #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
🎮 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
- Clean Inheritance: Drawable → UI components, proper type preservation
- Collection Consistency: Uniform iteration, indexing, and search patterns
- Resource Management: RAII everywhere, proper lifecycle handling
- 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
-
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
-
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
-
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)
- Proof of Concept: Simple SFML binding as Python extension
- Core Extraction: Separate rendering from Python embedding
- Module Design: Define clean API boundaries
- Incremental Migration: Move systems one at a time
- Compatibility Layer: Support existing games during transition
Example Usage (Future Vision)
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:
- FIX ANIMATION BLOCKERS for Tutorial Part 2:
- Implement input queueing during animations
- Add destination square reservation
- Test Pokemon-style continuous movement
- FIX GRID CLICKING (discovered broken in headless):
- Uncomment and implement click events
- Add tile coordinate conversion
- Enable nested grid support
- CREATE TUTORIAL ANNOUNCEMENT if blockers fixed
Weekend (July 13-14) - Tutorial Sprint:
- Regenerate Parts 3-6 (machine drafts are broken)
- Create Parts 7-10: Interface, Items, Targeting, Save/Load
- Create Parts 11-15: Dungeon levels, difficulty, equipment
- 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)
- Input Queue During Animation: Queue one additional move during animation
- Destination Square Reservation: Block target when movement begins
- Pokemon-Style Movement: Smooth continuous movement with input handling
- #119 - Animation Callbacks: Add completion callbacks with parameters
- #120 - Property Conflict Prevention: Prevent multiple animations on same property
- Remove Bare Pointers: Complete refactoring to weak references ✅
Grid System (6 issues)
- #111 - Grid Click Implementation: Fix commented-out events in headless
- Tile Coordinate Conversion: Convert mouse to tile coordinates
- Nested Grid Support: Enable clicking on grids within grids
- #123 - Grid Rendering Performance: Implement 256x256 subgrid system
- #116 - Dirty Flagging: Add dirty flag propagation from base
- #124 - Grid Point Animation: Enable animating individual tiles
Python API (6 issues)
- Regenerate Python Bindings: Create consistent interface generation
- #109 - Vector Class Enhancement: Add [0], [1] indexing to vectors
- #112 - Fix Object Splitting: Preserve Python derived class types
- #101/#110 - Standardize Constructors: Make all constructors consistent
- Color Class Bindings: Properly expose SFML Color class
- Font Class Bindings: Properly expose SFML Font class
Architecture (8 issues)
- #118 - Scene as Drawable: Refactor Scene to inherit from Drawable
- Scene Visibility System: Implement exclusive visibility switching
- Replace Transition System: Use animations not special transitions
- #122 - Parent-Child UI: Add parent field to UI drawables
- Collection Methods: Implement append/remove/extend with parent updates
- #121 - Timer Object System: Replace string-dictionary timers
- One-Shot Timer Mode: Implement proper one-shot functionality
- Button Mechanics: Any entity type can trigger buttons
Entity System (4 issues)
- Step-On Entities: Implement trigger when stepped on
- Bump Interaction: Add bump-to-interact behavior
- Type-Aware Interactions: Entity interactions based on type
- Button Mechanics: Any entity can trigger buttons
Tutorial & Documentation (4 issues)
- Fix Part 2 Tutorial: Unblock with animation fixes
- Regenerate Parts 3-6: Replace machine-generated content
- API Documentation: Document ergonomic improvements
- Tutorial Alignment: Ensure parts match TCOD structure
Last Updated: 2025-07-12 (CRITICAL TUTORIAL SPRINT) Next Review: July 15 after event start