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

21 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:

  • ✅ 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
  • 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

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) 🚀 NEXT!

Goal: Professional rendering capabilities

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 [QUICK WIN]
   grid.background_color = mcrfpy.Color(50, 50, 50)
   grid.background_texture = texture  # stretch/tile options
   
4. #106 - Shader support [STRETCH GOAL]
   sprite.shader = mcrfpy.Shader.load("glow.frag")
   frame.shader_params = {"intensity": 0.5}
   
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)

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

  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. 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. Scene Transitions - Fade, slide, custom effects (#105) - Completed Phase 5
  6. 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
  • #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

  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)

Last Updated: 2025-07-05