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