Update Design Proposals
parent
d65242a074
commit
0d4dab4598
1 changed files with 186 additions and 186 deletions
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue