diff --git a/Design-Proposals.-.md b/Design-Proposals.md similarity index 95% rename from Design-Proposals.-.md rename to Design-Proposals.md index 5434286..56c7c5f 100644 --- a/Design-Proposals.-.md +++ b/Design-Proposals.md @@ -1,187 +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 +# 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