diff --git a/Design-Proposals.-.md b/Design-Proposals.-.md new file mode 100644 index 0000000..c20b6b6 --- /dev/null +++ b/Design-Proposals.-.md @@ -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