Update Design Proposals
parent
a045672258
commit
16d769748a
|
|
@ -1,201 +1,201 @@
|
||||||
# Design Proposals
|
# Design Proposals
|
||||||
|
|
||||||
This page indexes all major architectural proposals and design documents for McRogueFace.
|
This page indexes all major architectural proposals and design documents for McRogueFace.
|
||||||
|
|
||||||
**Related Pages:**
|
**Related Pages:**
|
||||||
- [[Strategic-Direction]] - Project priorities and roadmap
|
- [[Strategic-Direction]] - Project priorities and roadmap
|
||||||
- [[Home]] - Documentation hub
|
- [[Home]] - Documentation hub
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Active Proposals
|
## Active Proposals
|
||||||
|
|
||||||
### Next-Generation Grid & Entity System
|
### Next-Generation Grid & Entity System
|
||||||
|
|
||||||
**Page:** [[Proposal-Next-Gen-Grid-Entity-System]]
|
**Page:** [[Proposal-Next-Gen-Grid-Entity-System]]
|
||||||
**Status:** Design Phase
|
**Status:** Design Phase
|
||||||
**Complexity:** Major architectural overhaul
|
**Complexity:** Major architectural overhaul
|
||||||
**Timeline:** 130-180 hours (3-4 months part-time)
|
**Timeline:** 130-180 hours (3-4 months part-time)
|
||||||
|
|
||||||
**Overview:** Comprehensive redesign of UIEntity/UIGrid systems to support:
|
**Overview:** Comprehensive redesign of UIEntity/UIGrid systems to support:
|
||||||
- Flexible entity content (any UIDrawable, not just sprites)
|
- Flexible entity content (any UIDrawable, not just sprites)
|
||||||
- Multi-tile entities (2x2, 3x3, arbitrary sizes)
|
- Multi-tile entities (2x2, 3x3, arbitrary sizes)
|
||||||
- Custom layer system (weather, particles, overlays)
|
- Custom layer system (weather, particles, overlays)
|
||||||
- Spatial optimization (O(1) entity queries)
|
- Spatial optimization (O(1) entity queries)
|
||||||
- Memory efficiency (optional gridstate, chunk loading)
|
- Memory efficiency (optional gridstate, chunk loading)
|
||||||
|
|
||||||
**Key Issues:**
|
**Key Issues:**
|
||||||
- [#115](../../issues/115) - SpatialHash for 10,000+ entities
|
- [#115](../../issues/115) - SpatialHash for 10,000+ entities
|
||||||
- [#116](../../issues/116) - Dirty flag system
|
- [#116](../../issues/116) - Dirty flag system
|
||||||
- [#113](../../issues/113) - Batch operations
|
- [#113](../../issues/113) - Batch operations
|
||||||
- [#117](../../issues/117) - Memory pool
|
- [#117](../../issues/117) - Memory pool
|
||||||
- [#123](../../issues/123) - Subgrid system
|
- [#123](../../issues/123) - Subgrid system
|
||||||
- [#124](../../issues/124) - Grid Point Animation
|
- [#124](../../issues/124) - Grid Point Animation
|
||||||
|
|
||||||
**Migration Strategy:** 4-phase backward-compatible rollout
|
**Migration Strategy:** 4-phase backward-compatible rollout
|
||||||
- Phase 1: Performance foundation (SpatialHash, dirty flags)
|
- Phase 1: Performance foundation (SpatialHash, dirty flags)
|
||||||
- Phase 2: Multi-tile support
|
- Phase 2: Multi-tile support
|
||||||
- Phase 3: Flexible content
|
- Phase 3: Flexible content
|
||||||
- Phase 4: Layer system
|
- Phase 4: Layer system
|
||||||
|
|
||||||
**Decision Status:** ⏳ Awaiting approval after Phase 1 (performance) completion
|
**Decision Status:** ⏳ Awaiting approval after Phase 1 (performance) completion
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Proposal Process
|
## Proposal Process
|
||||||
|
|
||||||
### Submitting a Proposal
|
### Submitting a Proposal
|
||||||
|
|
||||||
1. **Identify the problem** - What limitation are we addressing?
|
1. **Identify the problem** - What limitation are we addressing?
|
||||||
2. **Research current system** - Document existing architecture and shortcomings
|
2. **Research current system** - Document existing architecture and shortcomings
|
||||||
3. **Draft proposal** - Create wiki page with:
|
3. **Draft proposal** - Create wiki page with:
|
||||||
- Problem statement
|
- Problem statement
|
||||||
- Proposed solution
|
- Proposed solution
|
||||||
- Migration path
|
- Migration path
|
||||||
- Performance impact
|
- Performance impact
|
||||||
- Implementation complexity
|
- Implementation complexity
|
||||||
4. **Link related issues** - Connect to Gitea issues
|
4. **Link related issues** - Connect to Gitea issues
|
||||||
5. **Request review** - Discussion in issue comments or wiki discussion
|
5. **Request review** - Discussion in issue comments or wiki discussion
|
||||||
|
|
||||||
### Proposal Template
|
### Proposal Template
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
# Proposal: [Feature Name]
|
# Proposal: [Feature Name]
|
||||||
|
|
||||||
**Status:** [Design Phase / Under Review / Approved / Rejected / Implemented]
|
**Status:** [Design Phase / Under Review / Approved / Rejected / Implemented]
|
||||||
**Complexity:** [Minor / Moderate / Major]
|
**Complexity:** [Minor / Moderate / Major]
|
||||||
**Impact:** [Systems affected]
|
**Impact:** [Systems affected]
|
||||||
|
|
||||||
## Problem Statement
|
## Problem Statement
|
||||||
|
|
||||||
[What problem does this solve?]
|
[What problem does this solve?]
|
||||||
|
|
||||||
## Current Limitations
|
## Current Limitations
|
||||||
|
|
||||||
[What's broken or missing?]
|
[What's broken or missing?]
|
||||||
|
|
||||||
## Proposed Solution
|
## Proposed Solution
|
||||||
|
|
||||||
[High-level architecture and approach]
|
[High-level architecture and approach]
|
||||||
|
|
||||||
### Technical Details
|
### Technical Details
|
||||||
|
|
||||||
[Code examples, data structures, algorithms]
|
[Code examples, data structures, algorithms]
|
||||||
|
|
||||||
### Migration Path
|
### Migration Path
|
||||||
|
|
||||||
[How do we get from current to proposed without breaking existing code?]
|
[How do we get from current to proposed without breaking existing code?]
|
||||||
|
|
||||||
## Performance Impact
|
## Performance Impact
|
||||||
|
|
||||||
[Benchmarks, complexity analysis, memory impact]
|
[Benchmarks, complexity analysis, memory impact]
|
||||||
|
|
||||||
## Implementation Complexity
|
## Implementation Complexity
|
||||||
|
|
||||||
[Estimated effort, risk areas, dependencies]
|
[Estimated effort, risk areas, dependencies]
|
||||||
|
|
||||||
## Open Questions
|
## Open Questions
|
||||||
|
|
||||||
[Unknowns that need resolution]
|
[Unknowns that need resolution]
|
||||||
|
|
||||||
## Decision
|
## Decision
|
||||||
|
|
||||||
[Approved? Deferred? Alternative approach?]
|
[Approved? Deferred? Alternative approach?]
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Historical Context
|
## Historical Context
|
||||||
|
|
||||||
Many proposals emerge from:
|
Many proposals emerge from:
|
||||||
- **Strategic analysis** - FINAL_RECOMMENDATIONS.md identified foundation issues
|
- **Strategic analysis** - FINAL_RECOMMENDATIONS.md identified foundation issues
|
||||||
- **User feedback** - Tutorial burnout revealed animation system problems
|
- **User feedback** - Tutorial burnout revealed animation system problems
|
||||||
- **Performance profiling** - F3 overlay exposes bottlenecks
|
- **Performance profiling** - F3 overlay exposes bottlenecks
|
||||||
- **Issue tracking** - Patterns in open issues suggest architectural needs
|
- **Issue tracking** - Patterns in open issues suggest architectural needs
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Evaluation Criteria
|
## Evaluation Criteria
|
||||||
|
|
||||||
Proposals are evaluated on:
|
Proposals are evaluated on:
|
||||||
|
|
||||||
### 1. Alignment with Strategic Direction
|
### 1. Alignment with Strategic Direction
|
||||||
- Does it fix foundation issues?
|
- Does it fix foundation issues?
|
||||||
- Does it unblock tutorials?
|
- Does it unblock tutorials?
|
||||||
- Does it align with "beginner-friendly" mission?
|
- Does it align with "beginner-friendly" mission?
|
||||||
|
|
||||||
See [[Strategic-Direction]] for project priorities.
|
See [[Strategic-Direction]] for project priorities.
|
||||||
|
|
||||||
### 2. Technical Merit
|
### 2. Technical Merit
|
||||||
- Is the solution sound?
|
- Is the solution sound?
|
||||||
- Are tradeoffs clearly documented?
|
- Are tradeoffs clearly documented?
|
||||||
- Is performance impact understood?
|
- Is performance impact understood?
|
||||||
|
|
||||||
### 3. Implementation Feasibility
|
### 3. Implementation Feasibility
|
||||||
- Is effort estimate realistic?
|
- Is effort estimate realistic?
|
||||||
- Are dependencies clear?
|
- Are dependencies clear?
|
||||||
- Can it be done incrementally?
|
- Can it be done incrementally?
|
||||||
|
|
||||||
### 4. Backward Compatibility
|
### 4. Backward Compatibility
|
||||||
- Does it break existing code?
|
- Does it break existing code?
|
||||||
- Is migration path clear?
|
- Is migration path clear?
|
||||||
- Can old and new coexist?
|
- Can old and new coexist?
|
||||||
|
|
||||||
### 5. User Impact
|
### 5. User Impact
|
||||||
- Does it improve user experience?
|
- Does it improve user experience?
|
||||||
- Does it add complexity or simplify?
|
- Does it add complexity or simplify?
|
||||||
- Is it well-documented?
|
- Is it well-documented?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Deferred Proposals
|
## Deferred Proposals
|
||||||
|
|
||||||
*None currently. Deferred proposals will be listed here with rationale.*
|
*None currently. Deferred proposals will be listed here with rationale.*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Rejected Proposals
|
## Rejected Proposals
|
||||||
|
|
||||||
*None currently. Rejected proposals will be listed here with lessons learned.*
|
*None currently. Rejected proposals will be listed here with lessons learned.*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Completed Proposals
|
## Completed Proposals
|
||||||
|
|
||||||
### Profiling System (Issue #104)
|
### Profiling System (Issue #104)
|
||||||
|
|
||||||
**Status:** ✅ Implemented (October 2025)
|
**Status:** ✅ Implemented (October 2025)
|
||||||
**Complexity:** Moderate
|
**Complexity:** Moderate
|
||||||
**Implementation Time:** ~2 weeks
|
**Implementation Time:** ~2 weeks
|
||||||
|
|
||||||
**Overview:**
|
**Overview:**
|
||||||
- ScopedTimer RAII helper for instrumentation
|
- ScopedTimer RAII helper for instrumentation
|
||||||
- ProfilingMetrics struct in GameEngine
|
- ProfilingMetrics struct in GameEngine
|
||||||
- F3 overlay for real-time visualization
|
- F3 overlay for real-time visualization
|
||||||
- Benchmark scripts for baseline testing
|
- Benchmark scripts for baseline testing
|
||||||
|
|
||||||
**Impact:**
|
**Impact:**
|
||||||
- Enabled data-driven optimization decisions
|
- Enabled data-driven optimization decisions
|
||||||
- Identified grid rendering as primary bottleneck
|
- Identified grid rendering as primary bottleneck
|
||||||
- Provides user-visible performance feedback
|
- Provides user-visible performance feedback
|
||||||
|
|
||||||
**Related Pages:** [[Performance-and-Profiling]]
|
**Related Pages:** [[Performance-and-Profiling]]
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Proposal Status Legend
|
## Proposal Status Legend
|
||||||
|
|
||||||
- **Design Phase** - Proposal being drafted, research ongoing
|
- **Design Phase** - Proposal being drafted, research ongoing
|
||||||
- **Under Review** - Proposal complete, awaiting feedback
|
- **Under Review** - Proposal complete, awaiting feedback
|
||||||
- **Approved** - Green-lit for implementation
|
- **Approved** - Green-lit for implementation
|
||||||
- **In Progress** - Implementation underway
|
- **In Progress** - Implementation underway
|
||||||
- **Deferred** - Good idea, wrong timing
|
- **Deferred** - Good idea, wrong timing
|
||||||
- **Rejected** - Not aligned with project direction
|
- **Rejected** - Not aligned with project direction
|
||||||
- **Implemented** - Complete and merged
|
- **Implemented** - Complete and merged
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Navigation:**
|
**Navigation:**
|
||||||
- [[Home]] - Documentation hub
|
- [[Home]] - Documentation hub
|
||||||
- [[Strategic-Direction]] - Project priorities
|
- [[Strategic-Direction]] - Project priorities
|
||||||
- [[Proposal-Next-Gen-Grid-Entity-System]] - Active proposal
|
- [[Proposal-Next-Gen-Grid-Entity-System]] - Active proposal
|
||||||
Loading…
Reference in New Issue