Add "Design-Proposals"
parent
c62b7a7b8b
commit
71a8c16207
|
|
@ -0,0 +1,201 @@
|
|||
# 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…
Reference in New Issue