Update Design-Proposals: accurate issue statuses, add completed proposals
parent
35d5c12b68
commit
71d834ba39
2 changed files with 187 additions and 201 deletions
187
Design-Proposals.-.md
Normal file
187
Design-Proposals.-.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue