From 4b2ad0ff18f801d6ad080a49111493c01f555ef6 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Sun, 6 Jul 2025 14:43:43 -0400 Subject: [PATCH] docs: update roadmap for Phase 6 preparation - Mark Phase 5 (Window/Scene Architecture) as complete - Update issue statuses (#34, #61, #1, #105 completed) - Add Phase 6 implementation strategy for RenderTexture overhaul - Archive Phase 5 test files to .archive/ - Identify quick wins and technical approach for rendering work --- ROADMAP.md | 149 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 109 insertions(+), 40 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 1d060a2..d1589b8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -55,14 +55,17 @@ ## 🔧 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! +- ✅ **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) ### Active Development: - **Branch**: alpha_streamline_2 -- **Goal**: Complete architectural improvements for solid Beta foundation -- **Timeline**: 10-12 weeks comprehensive plan +- **Current Phase**: Phase 6 - Rendering Revolution (preparing to start) +- **Timeline**: 3-4 weeks for Phase 6 implementation - **Strategic Vision**: See STRATEGIC_VISION.md for platform roadmap ### 🏗️ Architectural Dependencies Map @@ -186,57 +189,79 @@ Rendering Layer: ``` *Rationale*: Performance is feature. Finding elements by name is huge QoL. -### Phase 5: Window/Scene Architecture (2-3 weeks) +### Phase 5: Window/Scene Architecture ✅ COMPLETE! (2025-07-06) **Goal**: Modern, flexible architecture ``` -1. #34 - Window object (singleton first) +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) +2. ✅ #1 - Window resize events + scene.on_resize(self, width, height) callback implemented -3. #61 - Scene object (OOP scenes) +3. ✅ #61 - Scene object (OOP scenes) class MenuScene(mcrfpy.Scene): - def on_keypress(self, key): + 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 - - Option 1: Use existing pysfml - - Option 2: mcrfpy.sfml submodule - - Option 3: Direct integration +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 - scene.fade_to(next_scene, duration=1.0) - scene.slide_out(direction="left") +5. ✅ #105 - Scene transitions + mcrfpy.setScene("menu", "fade", 1.0) + # Supports: fade, slide_left, slide_right, slide_up, slide_down ``` -*Rationale*: This is the "big leap" - modernizes the entire API. +*Result*: Entire window/scene system modernized with OOP design! -### Phase 6: Rendering Revolution (3-4 weeks) +### Phase 6: Rendering Revolution (3-4 weeks) 🚀 NEXT! **Goal**: Professional rendering capabilities ``` -1. #6 - RenderTexture overhaul +1. #6 - RenderTexture overhaul [CORE PRIORITY] - All UIDrawables render to RenderTexture - Enables clipping to parent bounds - Off-screen rendering for effects + - Technical challenges: + * Scene transition system now uses RenderTextures + * Need to preserve compatibility + * Performance implications for nested rendering 2. #8 - Viewport-based rendering - RenderTexture matches viewport - Proper scaling/letterboxing + - Coordinate system transformations -3. #50 - Grid background colors +3. #50 - Grid background colors [QUICK WIN] grid.background_color = mcrfpy.Color(50, 50, 50) + grid.background_texture = texture # stretch/tile options -4. #106 - Shader support - sprite.shader = "glow.frag" +4. #106 - Shader support [STRETCH GOAL] + sprite.shader = mcrfpy.Shader.load("glow.frag") + frame.shader_params = {"intensity": 0.5} -5. #107 - Particle system - particles = mcrfpy.ParticleEmitter() +5. #107 - Particle system [STRETCH GOAL] + emitter = mcrfpy.ParticleEmitter() + emitter.texture = spark_texture + emitter.emission_rate = 100 + emitter.lifetime = (0.5, 2.0) ``` + +**Phase 6 Technical Notes**: +- RenderTexture is the foundation - everything else depends on it +- Grid backgrounds (#50) can be done quickly as a warm-up +- Shader/Particle systems might be deferred to Phase 7 or Gamma +- Must maintain performance with nested RenderTextures +- Scene transitions already use RenderTextures - good integration test + *Rationale*: This unlocks professional visual effects but is complex. ### Phase 7: Documentation & Distribution (1-2 weeks) @@ -286,16 +311,60 @@ Rendering Layer: **Week 7-9**: Rendering revolution (or defer to gamma) **Week 10**: Documentation + release prep -### 🆕 **New Issues to Create** +### 🆕 **New Issues to Create/Track** -1. **Timer Objects** - Pythonic timer management (#103) -2. **Event System Enhancement** - Mouse enter/leave, drag, right-click -3. **Resource Manager** - Centralized asset loading -4. **Serialization System** - Save/load game state -5. **Scene Transitions** - Fade, slide, custom effects (#105) -6. **Profiling Tools** - Performance metrics (#104) -7. **Particle System** - Visual effects framework (#107) -8. **Shader Support** - Custom rendering effects (#106) +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 --- @@ -341,7 +410,7 @@ Rendering Layer: - [ ] **#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* +- [~] **#14** - Expose SFML as built-in module - *Research Complete, Implementation Pending* - [ ] **#46** - Subinterpreter threading tests - *Multiple Integrations* #### UI/Rendering System (12 issues) @@ -365,12 +434,12 @@ Rendering Layer: - [ ] **#20** - UIGrid get_grid_size standardization - *Multiple Integrations* - [x] **#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* +#### 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* -- [ ] **#1** - Scene resize event handling - *Isolated Fix* +- [x] **#1** - Scene resize event handling - *Completed Phase 5* ### 🔧 Quality of Life Features