john
/
McRogueFace
1
0
Fork 0
Code Issues 62 Pull Requests Projects 1 Releases Wiki Activity
McRogueFace/ROADMAP.md

16 KiB
Raw Blame History

McRogueFace - Development Roadmap

Project Status: 🎉 ALPHA 0.1 RELEASE! 🎉

Current State: Alpha release achieved! All critical blockers resolved!
Latest Update: Moved RenderTexture (#6) to Beta - Alpha is READY! (2025-07-05)
Branch: interpreter_mode (ready for alpha release merge)
Open Issues: ~46 remaining (non-blocking quality-of-life improvements)

Recent Achievements

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: Python Interpreter Mode & Automation API

Branch: interpreter_mode

Status: Actively implementing Python interpreter emulation features

Completed Features:

  • --exec flag implementation - Execute multiple scripts before main program

    • Scripts execute in order and share Python interpreter state
    • Proper sys.argv handling for main script execution
    • Compatible with -i (interactive), -c (command), and -m (module) modes

  • PyAutoGUI-compatible Automation API - Full automation testing capability

    • Screenshot capture: automation.screenshot(filename)
    • Mouse control: click(), moveTo(), dragTo(), scroll()
    • Keyboard input: typewrite(), hotkey(), keyDown(), keyUp()
    • Event injection into SFML render loop
    • Enables: Automated UI testing, demo recording/playback, accessibility testing

Architectural Decisions:

  1. Single-threaded design maintained - All Python runs in main thread between frames
  2. Honor system for scripts - Scripts must return control to C++ render loop
  3. Shared Python state - All --exec scripts share the same interpreter
  4. No threading complexity - Chose simplicity over parallelism (see THREADING_FOOTGUNS.md)
  5. Animation system in pure C++ - All interpolation happens in C++ for performance
  6. Property-based animation - Unified interface for all UI element properties

Key Files Created:

  • src/McRFPy_Automation.h/cpp - Complete automation API implementation
  • EXEC_FLAG_DOCUMENTATION.md - Usage guide and examples
  • AUTOMATION_ARCHITECTURE_REPORT.md - Design analysis and alternatives
  • Multiple example scripts demonstrating automation patterns

Addresses:

  • #32 - Executable behave like python command (90% complete - all major Python interpreter flags implemented)

Test Suite Results (2025-07-03):

Created comprehensive test suite with 13 tests covering all Python-exposed methods:

✅ Fixed Issues:

  • Fixed --exec Python interactive prompt bug (was entering REPL instead of game loop)
  • Resolved screenshot transparency issue (must use timer callbacks for rendered content)
  • Updated CLAUDE.md with testing guidelines and patterns

❌ Critical Bugs Found:

  1. SEGFAULT: Grid class crashes on instantiation (blocks all Grid functionality)
  2. #78 CONFIRMED: Middle mouse click sends 'C' keyboard event
  3. Entity property setters: "new style getargs format" error
  4. Sprite texture setter: Returns "error return without exception set"
  5. keypressScene(): Segfaults on non-callable arguments

📋 Missing Features Confirmed:

  • #73: Entity.index() method
  • #27: EntityCollection.extend() method
  • #41: UICollection.find(name) method
  • #38: Frame 'children' constructor parameter
  • #33: Sprite index validation

🚀 NEXT 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
  • #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
  • 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

✅ ALPHA 0.1 RELEASE ACHIEVED! (All Blockers Complete)

✅ All Alpha Requirements Complete!

  • #69 - Collections use Python Sequence Protocol - Completed! (2025-07-05)
  • #63 - Z-order rendering for UIDrawables - Completed! (2025-07-05)
  • #59 - Animation system for arbitrary UIDrawable fields - Completed! (2025-07-05)
  • #47 - New README.md for Alpha release - Completed
  • #3 - Remove deprecated McRFPy_API::player_input - Completed
  • #2 - Remove registerPyAction system - Completed

📋 Moved to Beta:

  • #6 - RenderTexture concept - Moved to Beta (not needed for Alpha)

🗂 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 - Extensive Overhaul
  • #46 - Subinterpreter threading tests - Multiple Integrations

UI/Rendering System (12 issues)

  • #63 ⚠️ Alpha Blocker - Z-order for UIDrawables - Multiple Integrations
  • #59 ⚠️ Alpha Blocker - Animation system - 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 - Extensive Overhaul
  • #34 - Window object for resolution/scaling - Extensive Overhaul
  • #62 - Multiple windows support - Extensive Overhaul
  • #49 - Window resolution & viewport controls - Multiple Integrations
  • #1 - Scene resize event handling - Isolated Fix

🔧 Quality of Life Features

UI Enhancement Features (8 issues)

  • #39 - Name field on UIDrawables - Multiple Integrations
  • #40 - only_one arg for unique naming - Multiple Integrations
  • #41 - .find(name) method for collections - Multiple Integrations
  • #38 - children arg for Frame initialization - Isolated Fix
  • #42 - Click callback arg for UIDrawable init - Isolated Fix
  • #27 - UIEntityCollection.extend() method - 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

🎯 RECOMMENDED TRIAGE SEQUENCE

Phase 1: Foundation Stabilization (1-2 weeks)

✅ COMPLETE AS OF 2025-01-03:
1. ✅ Fix Grid Segfault - Grid now supports None/null textures
2. ✅ Fix #78 Middle Mouse Click bug - Event type checking added
3. ✅ Fix Entity/Sprite property setters - PyVector conversion fixed
4. ✅ Fix #77 - Error message copy/paste bug fixed
5. ✅ Fix #74 - Grid.grid_y property added
6. ✅ Fix keypressScene() validation - Now rejects non-callable
7. ✅ Fix Sprite texture setter - No longer returns error without exception
8. ✅ Fix PyVector x/y properties - Were returning None

REMAINING IN PHASE 1:
9. ✅ Fix #73 - Entity.index() method for removal
10. ✅ Fix #27 - EntityCollection.extend() method
11. ✅ Fix #33 - Sprite index validation
12. Alpha Blockers (#3, #2) - Remove deprecated methods

Phase 2: Alpha Release Preparation (4-6 weeks)

1. Collections Sequence Protocol (#69) - Major refactor, alpha blocker
2. Z-order rendering (#63) - Essential UI improvement, alpha blocker  
3. RenderTexture overhaul (#6) - Core rendering improvement, alpha blocker
4. ✅ Animation system (#59) - COMPLETE! 30+ easing functions, all UI properties
5. ✅ Documentation (#47) - README.md complete, #48 dependency docs remaining

Phase 3: Engine Architecture (6-8 weeks)

1. Drawable base class (#71) - Clean up inheritance patterns  
2. Entity/Grid associations (#30) - Proper lifecycle management
3. Window object (#34) - Scene/window architecture
4. UIDrawable visibility (#10) - Rendering optimization

Phase 4: Advanced Features (8-12 weeks)

1. Grid strict mode (#16) - Entity knowledge/visibility system
2. SFML/TCOD integration (#14, #35) - Expose native libraries
3. Scene object refactor (#61) - Better input handling  
4. Name-based finding (#39, #40, #41) - UI element management
5. Demo projects (#54, #55, #36) - Showcase capabilities

Ongoing/Low Priority

- PyPI distribution (#70) - Community access
- Multiple windows (#62) - Advanced use cases  
- Grid stitching (#67) - Infinite world support
- Accessibility (#45) - Important but not blocking
- Subinterpreter tests (#46) - Performance research

📊 DIFFICULTY ASSESSMENT SUMMARY

Isolated Fixes (24 issues): Single file/function changes

  • Bugfixes: #77, #74, #37, #78
  • Simple features: #73, #52, #50, #33, #17, #38, #42, #27, #28, #26, #12, #1
  • Cleanup: #3, #2, #21, #47, #48

Multiple Integrations (28 issues): Cross-system changes

  • UI/Rendering: #63, #8, #9, #19, #39, #40, #41
  • Grid/Entity: #15, #20, #76, #46, #49, #75
  • Features: #54, #55, #53, #45, #7

Extensive Overhauls (26 issues): Major architectural changes

  • Core Systems: #69, #59, #6, #10, #30, #16, #67, #61, #34, #62
  • Integration: #71, #70, #32, #35, #14
  • Advanced: #36, #65

🎮 STRATEGIC DIRECTION

Engine Philosophy Maintained

  • C++ First: Performance-critical code stays in C++
  • Python Close Behind: Rich scripting without frame-rate impact
  • Game-Ready: Each improvement should benefit actual game development

Architecture Goals

  1. Clean Inheritance: Drawable → UI components, proper type preservation
  2. Collection Consistency: Uniform iteration, indexing, and search patterns
  3. Resource Management: RAII everywhere, proper lifecycle handling
  4. Multi-Platform: Windows/Linux feature parity maintained

Success Metrics for Alpha 0.1

  • All Alpha Blocker issues resolved (5 of 7 complete: #69, #59, #47, #3, #2)
  • Grid point iteration complete and tested
  • Clean build on Windows and Linux
  • Documentation sufficient for external developers
  • At least one compelling demo (Wumpus or Jupyter integration)

📚 REFERENCES & CONTEXT

Issue Dependencies (Key Chains):

  • Iterator System: Grid points → #73 → #69 (Alpha Blocker)
  • UI Hierarchy: #71 → #63 (Alpha Blocker)
  • Rendering: #6 (Alpha Blocker) → #8, #9 → #10
  • Entity System: #30 → #16 → #67
  • Window Management: #34 → #49, #61 → #62

Commit References:

  • 167636c: Iterator improvements (UICollection/UIEntityCollection complete)
  • Recent work: 7DRL 2025 completion, RPATH updates, console improvements

Architecture Files:

  • Iterator patterns: src/UICollection.cpp, src/UIGrid.cpp
  • Python integration: src/McRFPy_API.cpp, src/PyObjectUtils.h
  • Game implementation: src/scripts/ (Crypt of Sokoban complete game)

Last Updated: 2025-07-05
Total Open Issues: 62 (from original 78)
Alpha Status: 🎉 COMPLETE! All blockers resolved!
Achievement Unlocked: Alpha 0.1 Release Ready
Next Phase: Beta features including RenderTexture (#6), advanced UI patterns, and platform polish