diff --git a/Design-Proposals.-.md b/Design-Proposals.-.md new file mode 100644 index 0000000..5434286 --- /dev/null +++ b/Design-Proposals.-.md @@ -0,0 +1,187 @@ +# Design Proposals + +This page indexes major architectural proposals and design documents for McRogueFace. + +**Related Pages:** +- [[Strategic-Direction]] - Project priorities and roadmap +- [[Home]] - Documentation hub + +--- + +## Active Proposals + +### Next-Generation Grid & Entity System + +**Page:** [[Proposal-Next-Gen-Grid-Entity-System]] +**Status:** Partially Implemented +**Complexity:** Major architectural overhaul + +**Overview:** Comprehensive redesign of UIEntity/UIGrid systems to support: +- Flexible entity content (any UIDrawable, not just sprites) +- Multi-tile entities (2x2, 3x3, arbitrary sizes) +- Spatial optimization (O(1) entity queries) +- Memory efficiency (optional gridstate, chunk loading) + +**Completed Phases:** +- Phase 1 (Performance): SpatialHash ([#115](../issues/115) - Closed), dirty flags ([#116](../issues/116) - Closed), batch operations ([#113](../issues/113) - Closed) +- Dynamic layer system ([#147](../issues/147) - Closed) +- Chunk-based rendering ([#123](../issues/123) - Closed) +- Dirty flag RenderTexture caching ([#148](../issues/148) - Closed) + +**Remaining:** +- [#117](../issues/117) - Memory pool for entities (Open) +- [#124](../issues/124) - Grid point animation (Open) +- Multi-tile entity support ([#233](../issues/233), [#236](../issues/236), [#237](../issues/237) - Open) + +--- + +## Proposal Process + +### Submitting a Proposal + +1. **Identify the problem** - What limitation are we addressing? +2. **Research current system** - Document existing architecture and shortcomings +3. **Draft proposal** - Create wiki page with problem statement, solution, migration path, performance impact +4. **Link related issues** - Connect to Gitea issues +5. **Request review** - Discussion in issue comments + +### Proposal Template + +```markdown +# Proposal: [Feature Name] + +**Status:** [Design Phase / Under Review / Approved / Rejected / Implemented] +**Complexity:** [Minor / Moderate / Major] +**Impact:** [Systems affected] + +## Problem Statement +[What problem does this solve?] + +## Current Limitations +[What's broken or missing?] + +## Proposed Solution +[High-level architecture and approach] + +## Migration Path +[How to get from current to proposed without breaking existing code] + +## Performance Impact +[Benchmarks, complexity analysis, memory impact] + +## Implementation Complexity +[Estimated effort, risk areas, dependencies] +``` + +--- + +## Evaluation Criteria + +Proposals are evaluated on: + +1. **Alignment with Strategic Direction** - Does it fix foundation issues? Does it unblock tutorials? +2. **Technical Merit** - Is the solution sound? Are tradeoffs documented? +3. **Implementation Feasibility** - Is effort realistic? Can it be done incrementally? +4. **Backward Compatibility** - Does it break existing code? Is migration clear? +5. **User Impact** - Does it improve user experience? + +--- + +## Completed Proposals + +### Profiling System ([#104](../issues/104)) + +**Status:** Implemented (October 2025) +**Complexity:** Moderate + +- ScopedTimer RAII helper for instrumentation +- ProfilingMetrics struct in GameEngine +- F3 overlay for real-time visualization +- Benchmark API (`start_benchmark()`, `end_benchmark()`, `log_benchmark()`) + +**Related Pages:** [[Performance-and-Profiling]] + +### Dynamic Layer System ([#147](../issues/147)) + +**Status:** Implemented (November 2025) +**Complexity:** Major + +- ColorLayer and TileLayer as standalone objects +- Arbitrary number of layers per grid with z_index ordering +- Layers below entities (z < 0) and above entities (z >= 0) +- `grid.add_layer()`, `grid.remove_layer()`, `grid.layer("name")` + +**Related Pages:** [[Grid-Rendering-Pipeline]], [[Grid-System]] + +### Chunk-Based Rendering ([#123](../issues/123)) + +**Status:** Implemented (November 2025) +**Complexity:** Major + +- Large grids divided into chunks with per-chunk RenderTexture caching +- Only visible chunks processed (viewport culling) +- 1000x1000+ grids render efficiently + +**Related Pages:** [[Grid-Rendering-Pipeline]] + +### Dirty Flag Caching ([#148](../issues/148)) + +**Status:** Implemented (November 2025) +**Complexity:** Moderate + +- Layer changes mark containing chunks as dirty +- Unchanged chunks reuse cached RenderTexture +- Static scenes have near-zero CPU cost after initial render + +**Related Pages:** [[Grid-Rendering-Pipeline]], [[Performance-and-Profiling]] + +### Performance Foundation ([#113](../issues/113), [#115](../issues/115), [#116](../issues/116)) + +**Status:** Implemented (Late 2025) +**Complexity:** Major + +- SpatialHash for O(1) entity queries (`entities_in_radius()`) +- Dirty flag propagation through UIDrawable hierarchy +- Batch operations for grid manipulation + +**Related Pages:** [[Performance-Optimization-Workflow]] + +### Procedural Generation Systems ([#192](../issues/192)) + +**Status:** Implemented (January 2026) +**Complexity:** Major + +- HeightMap with noise generation, thresholding, kernel transforms +- BSP tree with splitting, iteration, adjacency queries +- NoiseSource with configurable octaves and lacunarity +- Integration with Grid layers (apply_threshold, apply_ranges) + +**Related Pages:** [[Procedural-Generation]] + +### Tiled/LDtk Import + +**Status:** Implemented (January 2026) +**Complexity:** Major + +- Tiled XML/JSON import with TileSetFile, WangSet types +- LDtk project import with AutoRuleSet pattern matching +- Wang tile terrain resolution and application + +--- + +## Proposal Status Legend + +- **Design Phase** - Proposal being drafted, research ongoing +- **Under Review** - Proposal complete, awaiting feedback +- **Approved** - Green-lit for implementation +- **In Progress** - Implementation underway +- **Deferred** - Good idea, wrong timing +- **Rejected** - Not aligned with project direction +- **Implemented** - Complete and merged + +--- + +**Navigation:** +- [[Home]] - Documentation hub +- [[Strategic-Direction]] - Project priorities +- [[Proposal-Next-Gen-Grid-Entity-System]] - Active proposal \ No newline at end of file diff --git a/Design-Proposals.md b/Design-Proposals.md deleted file mode 100644 index ed881f8..0000000 --- a/Design-Proposals.md +++ /dev/null @@ -1,201 +0,0 @@ -# Design Proposals - -This page indexes all major architectural proposals and design documents for McRogueFace. - -**Related Pages:** -- [[Strategic-Direction]] - Project priorities and roadmap -- [[Home]] - Documentation hub - ---- - -## Active Proposals - -### Next-Generation Grid & Entity System - -**Page:** [[Proposal-Next-Gen-Grid-Entity-System]] -**Status:** Design Phase -**Complexity:** Major architectural overhaul -**Timeline:** 130-180 hours (3-4 months part-time) - -**Overview:** Comprehensive redesign of UIEntity/UIGrid systems to support: -- Flexible entity content (any UIDrawable, not just sprites) -- Multi-tile entities (2x2, 3x3, arbitrary sizes) -- Custom layer system (weather, particles, overlays) -- Spatial optimization (O(1) entity queries) -- Memory efficiency (optional gridstate, chunk loading) - -**Key Issues:** -- [#115](../issues/115) - SpatialHash for 10,000+ entities -- [#116](../issues/116) - Dirty flag system -- [#113](../issues/113) - Batch operations -- [#117](../issues/117) - Memory pool -- [#123](../issues/123) - Subgrid system -- [#124](../issues/124) - Grid Point Animation - -**Migration Strategy:** 4-phase backward-compatible rollout -- Phase 1: Performance foundation (SpatialHash, dirty flags) -- Phase 2: Multi-tile support -- Phase 3: Flexible content -- Phase 4: Layer system - -**Decision Status:** ⏳ Awaiting approval after Phase 1 (performance) completion - ---- - -## Proposal Process - -### Submitting a Proposal - -1. **Identify the problem** - What limitation are we addressing? -2. **Research current system** - Document existing architecture and shortcomings -3. **Draft proposal** - Create wiki page with: - - Problem statement - - Proposed solution - - Migration path - - Performance impact - - Implementation complexity -4. **Link related issues** - Connect to Gitea issues -5. **Request review** - Discussion in issue comments or wiki discussion - -### Proposal Template - -```markdown -# Proposal: [Feature Name] - -**Status:** [Design Phase / Under Review / Approved / Rejected / Implemented] -**Complexity:** [Minor / Moderate / Major] -**Impact:** [Systems affected] - -## Problem Statement - -[What problem does this solve?] - -## Current Limitations - -[What's broken or missing?] - -## Proposed Solution - -[High-level architecture and approach] - -### Technical Details - -[Code examples, data structures, algorithms] - -### Migration Path - -[How do we get from current to proposed without breaking existing code?] - -## Performance Impact - -[Benchmarks, complexity analysis, memory impact] - -## Implementation Complexity - -[Estimated effort, risk areas, dependencies] - -## Open Questions - -[Unknowns that need resolution] - -## Decision - -[Approved? Deferred? Alternative approach?] -``` - ---- - -## Historical Context - -Many proposals emerge from: -- **Strategic analysis** - FINAL_RECOMMENDATIONS.md identified foundation issues -- **User feedback** - Tutorial burnout revealed animation system problems -- **Performance profiling** - F3 overlay exposes bottlenecks -- **Issue tracking** - Patterns in open issues suggest architectural needs - ---- - -## Evaluation Criteria - -Proposals are evaluated on: - -### 1. Alignment with Strategic Direction -- Does it fix foundation issues? -- Does it unblock tutorials? -- Does it align with "beginner-friendly" mission? - -See [[Strategic-Direction]] for project priorities. - -### 2. Technical Merit -- Is the solution sound? -- Are tradeoffs clearly documented? -- Is performance impact understood? - -### 3. Implementation Feasibility -- Is effort estimate realistic? -- Are dependencies clear? -- Can it be done incrementally? - -### 4. Backward Compatibility -- Does it break existing code? -- Is migration path clear? -- Can old and new coexist? - -### 5. User Impact -- Does it improve user experience? -- Does it add complexity or simplify? -- Is it well-documented? - ---- - -## Deferred Proposals - -*None currently. Deferred proposals will be listed here with rationale.* - ---- - -## Rejected Proposals - -*None currently. Rejected proposals will be listed here with lessons learned.* - ---- - -## Completed Proposals - -### Profiling System (Issue #104) - -**Status:** ✅ Implemented (October 2025) -**Complexity:** Moderate -**Implementation Time:** ~2 weeks - -**Overview:** -- ScopedTimer RAII helper for instrumentation -- ProfilingMetrics struct in GameEngine -- F3 overlay for real-time visualization -- Benchmark scripts for baseline testing - -**Impact:** -- Enabled data-driven optimization decisions -- Identified grid rendering as primary bottleneck -- Provides user-visible performance feedback - -**Related Pages:** [[Performance-and-Profiling]] - ---- - -## Proposal Status Legend - -- **Design Phase** - Proposal being drafted, research ongoing -- **Under Review** - Proposal complete, awaiting feedback -- **Approved** - Green-lit for implementation -- **In Progress** - Implementation underway -- **Deferred** - Good idea, wrong timing -- **Rejected** - Not aligned with project direction -- **Implemented** - Complete and merged - ---- - -**Navigation:** -- [[Home]] - Documentation hub -- [[Strategic-Direction]] - Project priorities -- [[Proposal-Next-Gen-Grid-Entity-System]] - Active proposal \ No newline at end of file