18 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: Alpha Streamline 2 - Major Architecture Improvements

Recent Completions:

✅ ISSUE_FIX_PLAN.md merged - Fixed 10+ critical issues
✅ Grid.at() flexible arguments - Tuple, keyword, and pos support
✅ Alpha 0.1 Release achieved - All blockers resolved!

Active Development:

Branch: alpha_streamline_2
Goal: Complete architectural improvements for solid Beta foundation
Timeline: 10-12 weeks comprehensive plan
Strategic Vision: See STRATEGIC_VISION.md for platform roadmap

🏗️ 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 (2-3 weeks)

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 = lambda w, h: handle_resize(w, h)
   
3. #61 - Scene object (OOP scenes)
   class MenuScene(mcrfpy.Scene):
       def on_keypress(self, key):
           # handle input
       def on_enter(self):
           # setup UI
           
4. #14 - SFML exposure research
   - Option 1: Use existing pysfml
   - Option 2: mcrfpy.sfml submodule
   - Option 3: Direct integration
   
5. 105 - Scene transitions
   scene.fade_to(next_scene, duration=1.0)
   scene.slide_out(direction="left")

Rationale: This is the "big leap" - modernizes the entire API.

Phase 6: Rendering Revolution (3-4 weeks)

Goal: Professional rendering capabilities

1. #6 - RenderTexture overhaul
   - All UIDrawables render to RenderTexture
   - Enables clipping to parent bounds
   - Off-screen rendering for effects
   
2. #8 - Viewport-based rendering
   - RenderTexture matches viewport
   - Proper scaling/letterboxing
   
3. #50 - Grid background colors
   grid.background_color = mcrfpy.Color(50, 50, 50)
   
4. #106 - Shader support
   sprite.shader = "glow.frag"
   
5. #107 - Particle system
   particles = mcrfpy.ParticleEmitter()

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
2. #86 - Add parameter documentation
3. #108 - Generate .pyi type stubs for IDE support
4. #70 - PyPI wheel preparation
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

Timer Objects - Pythonic timer management (#103)
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)
Profiling Tools - Performance metrics (#104)
Particle System - Visual effects framework (#107)
Shader Support - Custom rendering effects (#106)

🚀 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 - 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

🎮 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)

Last Updated: 2025-07-05

18 KiB Raw Blame History